{ "markdown": "# Apollo.io MCP Server\n\n\n\n\n

\n \"License\"\n \"GitHub\n \"Last\n \"Open\n \"PyPI\n \"PyPI\n \"Built\n

\n\n\n\nFastMCP server exposing the full operational surface of the Apollo.io REST API to Claude Code. 27 tools covering sequences, campaign health, mailbox warmup, people/org enrichment, CRM contacts, tasks, labels, credit tracking, AND programmatic template/sequence/mailbox-cap editing with audit logging.\n\nMost existing Apollo MCPs only expose people search and enrichment. This one is built for teams running outbound at scale — daily health digests, sequence management, mailbox deliverability monitoring, programmatic contact enrollment, and end-to-end sequence authoring without touching the Apollo UI.\n\n## Quick reference\n\n```\napollo_campaign_health — daily digest (start here)\napollo_messages_search days_back=1 — raw send/open/reply/bounce log\napollo_mailbox_warmup — per-mailbox deliverability state\napollo_sequences_list — all sequences + labels + stats\napollo_sequence_add_contacts ... — enroll contacts into a sequence\napollo_template_update ... — update template body + subject (with audit log)\napollo_sequence_create ... — author a new sequence end-to-end\napollo_step_create ... — add a step + template to a sequence\napollo_mailbox_update_cap ... — change daily send cap\napollo_credits_remaining — monthly credit budget check\napollo_health — self-check (also probes master key)\n```\n\n## Tool inventory (27)\n\n### Campaign health\n- `apollo_campaign_health(days_back=1)` — digest across all sequences + mailboxes\n- `apollo_mailbox_warmup()` — per-mailbox warmup status and daily limits\n- `apollo_sequence_get(sequence_id)` — one-sequence deep-dive\n\n### Sequences\n- `apollo_sequences_list()` — list all sequences with stats\n- `apollo_sequence_add_contacts(sequence_id, contact_ids, send_email_from_email_account_id?)`\n- `apollo_sequence_remove_contacts(sequence_id, contact_ids)`\n- `apollo_sequence_set_active(sequence_id, active)` — activate or pause\n\n### Messages / analytics\n- `apollo_messages_search(days_back, sequence_ids?, stats?, per_page, max_pages)`\n\n### People / orgs\n- `apollo_people_search(...)` — free (no credit burn)\n- `apollo_person_enrich(...)` — 1 credit per revealed email\n- `apollo_bulk_person_enrich(people, reveal_personal_emails?)` — up to 10/call\n- `apollo_org_search(...)`\n- `apollo_org_enrich(domain)`\n- `apollo_org_job_postings(organization_id)`\n\n### CRM\n- `apollo_contacts_search(...)`\n- `apollo_contact_create(...)`\n- `apollo_contact_update(contact_id, fields)`\n- `apollo_contact_stages()`\n\n### Tasks / labels / credits\n- `apollo_task_create(...)`\n- `apollo_labels_list()`\n- `apollo_label_create(name)`\n- `apollo_credits_remaining()`\n\n### Template + sequence authoring (destructive writes)\n- `apollo_template_get(template_id)` — fetch current template state\n- `apollo_template_update(template_id, subject?, body_text?, body_html?, audit_label?)` — update template subject + body. Snapshots current state to `APOLLO_AUDIT_LOG_PATH` (if set) BEFORE the write so any breakage is reversible from the diff\n- `apollo_sequence_create(name, label?, permissions?, active?)` — create a new sequence (paused by default)\n- `apollo_step_create(sequence_id, position, wait_days, subject, body_text, body_html?, step_type?, include_signature?)` — create a step + touch + template in one call\n- `apollo_mailbox_update_cap(mailbox_id, daily_send_limit, audit_label?)` — change daily send cap on a mailbox. Audits before/after.\n\n### Diagnostics\n- `apollo_health()` — probes API key validity + master-key hint\n\n## Configuration\n\nCopy `config.example.yaml` to `config.yaml` and fill in your values:\n\n```bash\ncp config.example.yaml config.yaml\n```\n\n`config.yaml` is gitignored. Key fields:\n\n| Field | Default | Description |\n|---|---|---|\n| `daily_send_target` | 50 | Used in health digest vs-target display |\n| `monthly_credit_pool` | 4000 | Alerts when `credit_alert_pct` consumed |\n| `sequence_labels` | `{}` | Map sequence IDs to human-readable names |\n| `mailbox_labels` | `{}` | Map email addresses to display names |\n\nEnv vars:\n\n| Var | Required | Description |\n|---|---|---|\n| `APOLLO_API_KEY` | Yes | Must be a **MASTER** key |\n| `APOLLO_MCP_CONFIG` | No | Override config.yaml path |\n| `APOLLO_MCP_TIMEOUT` | No | HTTP timeout in seconds (default 30) |\n| `APOLLO_AUDIT_LOG_PATH` | No | Path to a markdown file where destructive writes (template_update, sequence_create, step_create, mailbox_update_cap) append before/after diffs. Required for reversibility on the destructive-write tools. |\n\n## Install\n\nOpen Claude Code, paste:\n\n /plugin marketplace add adelaidasofia/apollo-mcp\n /plugin install apollo-mcp@apollo-mcp\n\nThen set `APOLLO_API_KEY` (must be a master key) in your environment and restart Claude Code.\n\n
\nLegacy install\n\n```bash\npip3 install -r requirements.txt\npython3 -c \"import server; print('OK')\"\n```\n\nAdd to your `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"apollo\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/apollo-mcp/server.py\"],\n \"env\": {\n \"APOLLO_API_KEY\": \"your-master-key-here\"\n }\n }\n }\n}\n```\n\nRestart Claude Code after editing `.mcp.json`.\n\n
\n\n## Known gotchas\n\n1. **MASTER key required** for `/emailer_campaigns`, `/emailer_messages/search`, `/email_accounts`, `/usage_stats/*`. Standard keys return 403. `apollo_health` probes for this automatically.\n\n2. **Rate limit** ~60 req/min. Built-in jittered exponential backoff handles 429s transparently.\n\n3. **Pagination** hard-capped at 50 pages × 100/page = 5,000 records per call. Slice by date for deeper queries.\n\n4. **Credit burn** — `apollo_person_enrich(reveal_personal_emails=True)` and the bulk variant each burn 1 credit.\n\n5. **5-minute in-memory cache** for `sequences_list`, `email_accounts`, `labels`, `contact_stages`. Force-refresh by restarting Claude Code.\n\n6. **Cloudflare 1010 on default Python UAs.** apollo.io returns HTTP 403 with body `error code: 1010` when it sees `python-urllib/*` or `python-httpx/*` user-agents. The server spoofs `apollo-mcp/1.0 (curl/8.0.0)` to bypass. If you build any adjacent scripts hitting apollo.io, add the same `User-Agent` header or you'll debug a phantom 403 that looks like a missing master key.\n\n7. **No working sequence-scoped unenroll endpoint.** `POST /emailer_campaigns/{id}/remove_contact_ids` returns 404. The no-ID variant `POST /emailer_campaigns/remove_contact_ids` returns 200 but is a silent no-op regardless of payload. The only reliable unenroll path is `DELETE /contacts/{id}`, which cascades all campaign enrollments. Destructive: the contact record is marked `deleted: true`. `apollo_sequence_remove_contacts` wraps this.\n\n8. **`GET /emailer_campaigns` creates an empty sequence.** Use `POST /emailer_campaigns/search` to list sequences. The server does this correctly — just be careful if you hit the API directly.\n\n9. **Sequence activation uses `PUT`, not a sub-resource.** The correct endpoint to activate or pause a sequence is `PUT /emailer_campaigns/{id}` with body `{\"emailer_campaign\": {\"active\": true/false}}`. Sub-resource paths like `/check_contacts` return 404.\n\n## Scripts\n\n- `scripts/daily_digest.py` — standalone script that pulls yesterday's stats and prepends them to a markdown dashboard. Run via cron or manually.\n- `scripts/bootstrap_sequences.py` — create sequences programmatically from code. Useful for version-controlling email copy. Includes the undocumented `POST /emailer_touches/{id}/approve` endpoint needed to move steps out of draft state.\n\n## Related MCPs\n\nSame author, same architecture pattern (FastMCP, draft+confirm on writes where applicable, vault auto-export, MIT):\n\n- [slack-mcp](https://github.com/adelaidasofia/slack-mcp) — multi-workspace Slack\n- [imessage-mcp](https://github.com/adelaidasofia/imessage-mcp) — macOS iMessage\n- [whatsapp-mcp](https://github.com/adelaidasofia/whatsapp-mcp) — WhatsApp via whatsmeow\n- [google-workspace-mcp](https://github.com/adelaidasofia/google-workspace-mcp) — Gmail / Calendar / Drive / Docs / Sheets\n- [substack-mcp](https://github.com/adelaidasofia/substack-mcp) — Substack writing + analytics\n- [luma-mcp](https://github.com/adelaidasofia/luma-mcp) — lu.ma events\n- [parse-mcp](https://github.com/adelaidasofia/parse-mcp) — markitdown / Docling / LlamaParse router\n- [rescuetime-mcp](https://github.com/adelaidasofia/rescuetime-mcp) — RescueTime productivity data\n- [graph-query-mcp](https://github.com/adelaidasofia/graph-query-mcp) — vault knowledge graph queries\n- [graph-autotagger-mcp](https://github.com/adelaidasofia/graph-autotagger-mcp) — wikilink suggestions from the graph\n- [investor-relations-mcp](https://github.com/adelaidasofia/investor-relations-mcp) — seed-raise pipeline tracker\n- [vault-sync-mcp](https://github.com/adelaidasofia/vault-sync-mcp) — bidirectional vault sync\n\n\n## Telemetry\n\nThis plugin sends a single anonymous install signal to `myceliumai.co` the first time it loads in a Claude Code session on a given machine.\n\n**What is sent:**\n- Plugin name (e.g. `slack-mcp`)\n- Plugin version (e.g. `0.1.0`)\n\n**What is NOT sent:**\n- No user identifiers, names, emails, tokens, or API keys\n- No file paths, message content, or anything from your work\n- No IP address is stored after dedup processing\n\n**Why:** Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.\n\n**Opt out:** Set the environment variable `MYCELIUM_NO_PING=1` before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at `~/.mycelium/onboarded-` — delete it if you want to reset state.\n\n## License\n\nMIT\n\n---\n\nBuilt by [Mycelium AI](https://myceliumai.co). Full install or team version at [diazroa.com](https://diazroa.com).\n", "bytes": 11081, "sha": "acf26450019d743567cfb4e668d54ffaf04d36021c4251a6057283f5aff4b6aa", "repo_slug": "adelaidasofia/apollo-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_adelaidasofia_apollo_mcp_0a73fa7a/readme" }