Content
# Apollo.io MCP Server
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
A secure [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes **42 tools** covering the full Apollo.io REST API v1. Works with any MCP-compatible AI assistant or client.
## Features
- **42 tools** across 9 domains (people, organizations, contacts, accounts, deals, sequences, tasks, emails, admin)
- **Confirm gate** — write operations require explicit `confirm: true` to execute, preventing accidental mutations
- **Strict input validation** — every tool uses Zod schemas with `.strict()`, rejecting unknown fields
- **ID sanitization** — all IDs validated before URL interpolation, preventing path traversal
- **Rate limiting** — client-side token bucket (5 req/s, burst 10) with exponential backoff on 429/5xx
- **Secure by default** — API key only via header, no sensitive data in logs, all logs to stderr
## Installation
### From npm
```bash
npx apollo-io-mcp-server --api-key=YOUR_API_KEY
```
### From source
```bash
git clone https://github.com/erickhuge/apollo-io-mcp-server.git
cd apollo-io-mcp-server
npm install
npm run build
```
## Configuration
Get your API key from [Apollo.io Settings > API](https://app.apollo.io/).
### MCP Client Configuration
Add to your MCP client settings (e.g., `settings.json`, `mcp.json`, or equivalent):
```json
{
"mcpServers": {
"apollo-io": {
"command": "npx",
"args": ["-y", "apollo-io-mcp-server"],
"env": {
"APOLLO_IO_API_KEY": "your-api-key"
}
}
}
}
```
### From source
```json
{
"mcpServers": {
"apollo-io": {
"command": "node",
"args": ["/path/to/apollo-io-mcp-server/dist/index.js"],
"env": {
"APOLLO_IO_API_KEY": "your-api-key"
}
}
}
}
```
### Environment variables
| Variable | Description | Default |
|----------|-------------|---------|
| `APOLLO_IO_API_KEY` | Your Apollo.io API key (required) | — |
| `LOG_LEVEL` | Logging level: `error`, `warn`, `info`, `debug` | `error` |
You can also pass the API key as a CLI argument: `--api-key=YOUR_KEY`
## Available Tools (42)
### People (5 tools)
| Tool | Type | Description |
|------|------|-------------|
| `people_search` | read | Search for people by company domains, titles, seniority, locations, departments |
| `people_enrich` | read | Enrich data for a single person by name, email, domain, or LinkedIn URL |
| `people_bulk_enrich` | read | Enrich data for up to 10 people at once |
| `people_reveal_email` | **write** | Reveal email addresses by Apollo entity IDs (consumes credits) |
| `people_find_employees` | read | Find employees of a company by name, with optional title/seniority filters |
### Organizations (5 tools)
| Tool | Type | Description |
|------|------|-------------|
| `org_search` | read | Search organizations by domains, locations, employee count, name |
| `org_enrich` | read | Enrich data for a single organization by domain or name |
| `org_bulk_enrich` | read | Enrich data for up to 10 organizations by domain |
| `org_get` | read | Get complete organization info by Apollo ID |
| `org_job_postings` | read | Get job postings for a specific organization |
### Contacts — CRM (8 tools)
| Tool | Type | Description |
|------|------|-------------|
| `contacts_search` | read | Search contacts in your Apollo CRM |
| `contacts_create` | **write** | Create a new contact |
| `contacts_update` | **write** | Update an existing contact by ID |
| `contacts_bulk_create` | **write** | Create up to 100 contacts at once |
| `contacts_bulk_update` | **write** | Update up to 100 contacts at once |
| `contacts_update_stages` | **write** | Update stage for multiple contacts |
| `contacts_update_owners` | **write** | Update owner for multiple contacts |
| `contacts_list_stages` | read | List all contact stages |
### Accounts — CRM (7 tools)
| Tool | Type | Description |
|------|------|-------------|
| `accounts_search` | read | Search accounts in your Apollo CRM |
| `accounts_create` | **write** | Create a new account |
| `accounts_update` | **write** | Update an existing account by ID |
| `accounts_bulk_create` | **write** | Create up to 100 accounts at once |
| `accounts_update_stages` | **write** | Update stage for multiple accounts |
| `accounts_update_owners` | **write** | Update owner for multiple accounts |
| `accounts_list_stages` | read | List all account stages |
### Deals (5 tools)
| Tool | Type | Description |
|------|------|-------------|
| `deals_search` | read | Search deals (opportunities) in your CRM |
| `deals_create` | **write** | Create a new deal |
| `deals_get` | read | Get deal details by opportunity ID |
| `deals_update` | **write** | Update an existing deal |
| `deals_list_stages` | read | List all deal stages |
### Sequences (3 tools)
| Tool | Type | Description |
|------|------|-------------|
| `sequences_search` | read | Search email sequences |
| `sequences_add_contacts` | **write** | Add contacts to a sequence |
| `sequences_remove_contacts` | **write** | Remove/stop contacts from a sequence |
### Tasks (2 tools)
| Tool | Type | Description |
|------|------|-------------|
| `tasks_search` | read | Search tasks by keywords, status |
| `tasks_bulk_create` | **write** | Create up to 100 tasks at once |
### Emails (3 tools)
| Tool | Type | Description |
|------|------|-------------|
| `emails_search` | read | Search outreach emails by sequence or contact |
| `emails_get_stats` | read | Get engagement stats for a specific email |
| `emails_list_accounts` | read | List linked email accounts |
### Admin (4 tools)
| Tool | Type | Description |
|------|------|-------------|
| `admin_list_users` | read | List team members |
| `admin_list_custom_fields` | read | List custom fields |
| `admin_create_custom_field` | **write** | Create a new custom field |
| `admin_api_usage` | read | View API usage stats and rate limits |
## Write Safety: Confirm Gate
All **write** operations (marked in bold above) require a `confirm: true` parameter to execute. Without it, the tool returns a preview of what would happen:
```
User: "Create a contact for John Doe"
AI calls: contacts_create({ first_name: "John", last_name: "Doe" })
Returns: "Write operation: contacts_create
This will execute with the following parameters:
first_name: "John"
last_name: "Doe"
To proceed, call this tool again with confirm: true"
User: "Yes, go ahead"
AI calls: contacts_create({ first_name: "John", last_name: "Doe", confirm: true })
Returns: { contact: { id: "...", first_name: "John", ... } }
```
This prevents the AI from accidentally creating, updating, or deleting data without explicit user approval.
## Security
- **Input validation**: Every tool validates input with strict Zod schemas. Unknown fields are rejected. IDs are validated against `/^[a-zA-Z0-9_-]+$/` before being used in URL paths.
- **API key handling**: Sent only via `x-api-key` HTTP header. Never logged, never included in request bodies or query parameters.
- **Logging**: All logs go to stderr (stdout is reserved for MCP protocol). Only HTTP method + path are logged, never request/response payloads.
- **Rate limiting**: Client-side token bucket prevents excessive API usage. Automatic retry with exponential backoff on rate limits (429) and server errors (5xx).
## Architecture
```
src/
index.ts Server bootstrap
core/
types.ts ToolDefinition, logger, error types
client.ts HTTP client (rate limit, retry, auth)
validation.ts Zod helpers, ID sanitization
confirmation.ts Confirm gate for write ops
registry.ts Tool registry and MCP binding
domains/
people/ 5 tools
organizations/ 5 tools
contacts/ 8 tools
accounts/ 7 tools
deals/ 5 tools
sequences/ 3 tools
tasks/ 2 tools
emails/ 3 tools
admin/ 4 tools
```
Each domain module exports an array of `ToolDefinition` objects. The registry collects all tools and binds them to the MCP server. Adding new tools means adding entries to the appropriate domain module.
## License
MIT
