apollo-mcp

Apollo.io tools for agents, MCP clients, and the command line.

apollo-mcp exposes Apollo's B2B data APIs through a Model Context Protocol server built with FastMCP 3. It also ships apollo-cli, a small command-line wrapper for the most common search and enrichment workflows.

Highlights

• 45 MCP tools spanning prospect search, enrichment, CRM records, deals, tasks, sequences, email engagement, phone calls, and API usage stats.

• Two transports — stdio for Claude Desktop, Claude Code, and local MCP clients; Streamable HTTP for hosted or remote deployments.

• Per-request auth in HTTP mode so one environment key is never shared across remote clients or organizations.

• Defensive request construction for Apollo's endpoint-specific wire-format quirks (see Apollo Wire-Format Notes).

• A CLI for quick search and enrichment without writing any code.

• 288 tests — 255 unit plus 33 live integration tests, with the unit suite alone covering most of the package.

Related MCP server: apollo-io-mcp-server

Contents

• Quickstart

• Installation

• Configuration

• MCP Server

• CLI

• Tool Catalog

• Apollo Wire-Format Notes

• Development

• Testing

• Security

• Contributing

• License

Quickstart

git clone https://github.com/dyngai/apollo-mcp.git
cd apollo-mcp
uv sync --extra dev

cp env.example .env        # then set APOLLO_API_KEY in .env

Run the MCP server over stdio:

uv run apollo-mcp

Or run a CLI command:

uv run apollo-cli search-people \
  --person_titles "Manager,Director" \
  --person_locations "Virginia"

Installation

With uv

uv is the recommended workflow for local development:

uv sync                 # runtime dependencies
uv sync --extra dev     # plus pytest, respx, coverage

With pip

pip install -e .
pip install -e ".[dev]"

Both install the apollo-mcp and apollo-cli console scripts.

Configuration

python-dotenv is loaded automatically, so a local .env file works for stdio and CLI usage.

MCP Server

apollo-mcp                               # stdio (default)
apollo-mcp --transport http              # HTTP on 127.0.0.1:8000/mcp/
apollo-mcp --transport http --host 0.0.0.0 --port 9000 --path /api/mcp/
apollo-mcp --transport sse --port 8001   # legacy SSE transport
apollo-mcp --version
apollo-mcp --help

Claude Desktop / Claude Code

For stdio-based clients, point the MCP client at apollo-mcp and pass the Apollo key in the server environment:

{
  "mcpServers": {
    "apollo": {
      "command": "apollo-mcp",
      "env": {
        "APOLLO_API_KEY": "your-apollo-api-key",
        "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"
      }
    }
  }
}

You can also use a virtualenv-relative command such as .venv/bin/apollo-mcp, or run through uvx.

HTTP / Remote Clients

apollo-mcp --transport http --host 0.0.0.0 --port 8000

The endpoint is then available at http://<host>:8000/mcp/, and every request must carry its own Apollo key:

Authorization: Bearer <apollo-api-key>

Each distinct bearer token gets one long-lived ApolloClient, so HTTP connections and TLS sessions are pooled and reused across tool calls rather than renegotiated every time. The cache is bounded, and the least-recently-used client is closed on eviction.

If you deploy behind a reverse proxy or TLS terminator, forward the configured --path prefix unchanged.

Docker

docker build -t apollo-mcp .
docker run --rm -p 8080:8080 apollo-mcp

The container starts the HTTP transport on 0.0.0.0:8080/mcp/ as a non-root user. Clients still need to send Authorization: Bearer <apollo-api-key>.

CLI

The CLI covers the highest-leverage search and enrichment commands.

# Search for people. Apollo requires at least person_titles for this flow.
apollo-cli search-people \
  --person_titles "Manager,Director" \
  --person_locations "Virginia"

# Find a specific person by enrichment instead of broad search.
apollo-cli enrich-person \
  --first_name "John" \
  --last_name "Doe" \
  --organization_name "Company"

# Other examples.
apollo-cli enrich-person --email "tim@apollo.io"
apollo-cli search-companies --q "technology" --organization_num_employees_ranges "51,200"
apollo-cli org-jobs --id "5e66b6381e05b4008c8331b8" --page 2 --per_page 50

Argument conventions

• --key value and --key=value are both supported.

• Comma-separated values become arrays: --person_titles "CEO,CTO,VP".

• Employee ranges keep their comma as one range: --organization_num_employees_ranges "11,20" becomes ["11,20"].

• Complex request bodies can be passed with --json '{"q":"test","page":1}'.

• Bare digits become integers (--page 2), but values with a leading zero stay strings so identifiers like --postal_code 02134 are preserved intact.

apollo-cli --help
apollo-cli <command> --help

Tool Catalog

Apollo Wire-Format Notes

Apollo's API has several endpoint-specific request shapes that this package handles explicitly.

Request construction

• People-search filters are sent as URL query parameters with bracket notation: person_titles[]=VP&person_titles[]=CTO. Sending them in the JSON body is silently ignored and returns arbitrary results.

• People-search aliases such as q, company_domains, and q_organization_domains are normalized to the current Apollo fields q_keywords and q_organization_domains_list[]. An explicitly supplied canonical field always wins over its alias.

• Range filters serialize with bracketed sub-keys — revenue_range[min]=100 — and booleans render lowercase (true/false) as Apollo expects.

• Company employee ranges accept dash format at the MCP boundary ("11-20") and are normalized to Apollo's comma format ("11,20").

• Apollo uses PATCH to update contacts, accounts, deals, and phone calls.

• bulk_enrich_organizations expects {"domains": [...]}, not objects; bulk_enrich_people expects {"details": [...]}, not {"people": [...]}.

• Caller-supplied IDs interpolated into URL paths are URL-encoded to prevent path traversal and query-string injection.

Pagination

per_page is capped at 100. Apollo rejects larger values outright with HTTP 422 (Per page not supported on people search, Per Page Limit Crossed. on company search) rather than clamping them, so the MCP schema enforces 1–100 before a request is ever sent.

Responses

• apollo_search_people and apollo_search_companies always return compact per-result summaries so MCP clients do not receive unnecessarily large payloads.

• apollo_enrich_person and apollo_get_person are compact by default but accept full=true for the raw Apollo record — those can exceed 100 KB and may overflow MCP token limits, so reach for it only when you need the complete employment_history / current_technologies / organization block.

• The lower-level ApolloClient never trims; it always returns the raw response.

• Endpoints that answer 204 No Content — sequence approve, abort, and archive, and bulk task completion — decode to {} rather than raising.

• A non-JSON body (for example an upstream HTML error page returned with a 200) raises an ApolloError naming the status, content type, and a body snippet, instead of a bare JSON decoding error.

Development

apollo_mcp/
  apollo.py     # ApolloClient: httpx wrapper, errors, redirects, query strings
  server.py     # FastMCP server and all tool registrations
  cli.py        # apollo-cli argument parsing and command dispatch

tests/
  test_apollo.py        # respx-mocked client tests
  test_server.py        # FastMCP tool tests with a fake Apollo client
  test_cli.py           # subprocess and in-process CLI tests
  test_integration.py   # live Apollo API tests, auto-skip without a key

uv sync --extra dev      # install development dependencies
uv run apollo-mcp        # run the server locally
uv run apollo-cli --help # run the CLI locally

Testing

# Unit tests only — no Apollo key required.
pytest -m "not integration"

# Live integration tests only.
APOLLO_API_KEY=... pytest -m integration

# Everything.
APOLLO_API_KEY=... pytest

# With coverage.
APOLLO_API_KEY=... pytest --cov=apollo_mcp --cov-report=term-missing

The integration suite is marked integration and auto-skips when APOLLO_API_KEY is not set. Those tests are read-only — searches, enrichments, and stage listings — so they do not mutate CRM data, though enrichment calls do consume Apollo credits.

The unit suite covers 92% of the package on its own; the badge above tracks that figure, since it is the one reproducible without an Apollo key.

python scripts/coverage_badge.py --write   # refresh them
python scripts/coverage_badge.py --check   # verify (CI runs this)

Security

• Do not commit Apollo API keys.

• .env and .mcp.json are gitignored because they commonly contain secrets.

• API keys are never intentionally logged by the package.

• HTTP transport requires Authorization: Bearer <apollo-api-key> per request and never falls back to a server-side environment key.

• Path traversal and query-string injection regressions are covered in tests/test_apollo.py.

If you open an issue, remove API keys, emails, tokens, and other sensitive customer data from logs and screenshots first.

Contributing

Contributions are welcome.

1. Fork the repository.

2. Create a feature branch.

3. Add or update tests for behavioral changes.

4. Run the relevant commands from Testing.

5. Open a pull request with a concise description of the change.

For API-shape changes, prefer tests that assert the exact HTTP method, path, query string, and JSON body sent to Apollo.

License

MIT. See LICENSE.