mcp-server-apollo

MCP (Model Context Protocol) server for the Apollo.io B2Bdiscovery and enrichment API: company search, people search, contactenrichment (emails/phones), organization firmographics, and API usage stats.

The server wraps Apollo's REST API with one account-level API key keptserver-side. It is read-only by design: no sequences, no emailer, no CRMwrites, no account management.

Tools

Tool	Risk	Apollo endpoint
`apollo_search_capabilities`	read	— (local discovery)
`apollo_companies_search`	read + 1 credit/page	`POST /mixed_companies/search`
`apollo_people_search`	read (free, master key)	`POST /mixed_people/api_search`
`apollo_person_enrich`	read + credits	`POST /people/match`
`apollo_people_bulk_enrich`	read + credits	`POST /people/bulk_match` (chunked ×10)
`apollo_org_enrich`	read + 1 credit	`GET /organizations/enrich`
`apollo_webhook_result`	read (free)	`GET /webhook_result/{request_id}`
`apollo_credit_usage`	read (free, master key)	`POST /usage_stats/api_usage_stats`

Notes that save you a support ticket:

People search returns no contact data. Apollo's currentmixed_people/api_search endpoint deliberately obfuscates last names andomits emails/phones. Feed the returned person id intoapollo_person_enrich to get contact data (that is what costs credits).
Phone reveals are asynchronous. reveal_phone_number=true requires apublic HTTPS webhookUrl; Apollo POSTs the numbers there minutes later. Thesynchronous response carries a request_id — poll apollo_webhook_resultwith it if the callback is missed (results kept 30 days).
Master API key. apollo_people_search and apollo_credit_usage requirea master Apollo API key (Apollo returns 403 API_INACCESSIBLE otherwise).
No credit-balance API. Apollo only exposes per-endpoint rate-limit usage;the remaining credit balance lives in the Apollo UI (Settings → Billing).
Field projection. Every data tool accepts fields[] dot-paths to shrinkresponses; company search applies a slim default projection (pass ["*"]for full records).

Usage

npm install
npm run build

# stdio transport (Claude Desktop, local MCP clients)
APOLLO_API_KEY=... node dist/transports/stdio.js

# streamable HTTP transport on :3000/mcp
APOLLO_API_KEY=... MCP_HTTP_TOKEN=... node dist/transports/http.js

Configuration (see .env.example): APOLLO_API_KEY (required),APOLLO_TIMEOUT_MS, APOLLO_AUDIT_LOG (JSONL audit trail; hashed targets,never raw arguments or secrets), and for HTTP: MCP_HTTP_HOST, PORT,MCP_HTTP_TOKEN (static bearer), MCP_ALLOWED_ORIGINS, MCP_MAX_BODY_BYTES.

There is also an embeddable gateway export (mcp-server-apollo/gateway) thatexposes the same tools as plain functions with JSON-schema definitions.

Security

The API key is read only from the server environment, sent only in thex-api-key header over HTTPS, and redacted from error messages and logs.
Tool calls pass a policy allowlist; anything unlisted is denied.
All tools are annotated read-only/non-destructive; credit-consuming toolsstate their cost in the description so agents confirm spend with the user.
HTTP transport binds to loopback by default, validates Origin, caps bodysize, and supports a static bearer token for upstream auth proxies.
Rate limits: HTTP 429 is retried with jittered backoff honouringretry-after; bulk enrichment runs at low bounded concurrency becauseApollo limits bulk_match hard (documented 20/min).

Development

npm run typecheck
npm test
npm run smoke:live   # needs a real APOLLO_API_KEY; uses ~1 credit

License

Apache-2.0

mcp-server-apollo