instantly-mcp

A local stdio MCP server that exposes the Instantly.ai v2 API to Claude Code — the same way crmdata exposes HubSpot, but with no dashboard, no database, no hosting. Just the tools.

Claude Code ──stdio──▶ node src/server.mjs ──HTTPS+Bearer──▶ Instantly v2 API

Setup

cd instantly-mcp
npm install
cp .env.example .env      # then paste your INSTANTLY_API_KEY
npm run smoke             # boots the server, lists tools, does one live read

Get the key from Instantly → Settings → Integrations → API keys.

Wire it into Claude Code

Use absolute paths (stdio launches the process directly):

claude mcp add instantly -- node --env-file="C:/Users/colen/OneDrive/Desktop/Code-Projects/instantly-mcp/.env" "C:/Users/colen/OneDrive/Desktop/Code-Projects/instantly-mcp/src/server.mjs"

Verify:

claude mcp list

Then just ask, in any Claude Code session:

"How are my Instantly campaigns doing this week, and is any sending account's warmup health dropping?"

Tools

Read

Tool	What it does
list_campaigns	Campaigns with ids, names, status
get_campaign_analytics	Sent/open/reply stats (one campaign or all)
list_accounts	Connected sending inboxes
warmup_analytics	Inbox-vs-spam + 0–100 health per account
account_vitals	SPF/DKIM/DMARC deliverability checks
list_emails	Unibox (address or thread:<id>)
get_email	One email, full body
unread_count	Unread count
list_leads_in_campaign	Leads on a campaign

Write — staging (no send)

Tool	What it does
create_campaign	Create a sequence + schedule (does not launch)
add_leads	Bulk-add leads to a campaign
mark_thread_read	Mark a unibox thread read

Write — LIVE SEND (require confirm: true)

Tool	What it does
activate_campaign	Launches a campaign — it starts sending
reply_to_email	Sends a reply into a unibox thread

The two live-send tools refuse unless you pass confirm: true, so cold email is never fired on a one-word ask.

Files

src/client.mjs   thin Instantly v2 fetch wrapper (zero deps)
src/tools.mjs    tool definitions (name, description, zod schema, handler)
src/server.mjs   McpServer + stdio transport
scripts/smoke.mjs  end-to-end boot + tools/list test

Notes

• All 9 read tools are verified live against the real workspace (2026-07-17). Two endpoints ported from salesintel were stale against the current v2 API and were corrected here: warmup is POST /accounts/warmup-analytics (hyphen), and vitals takes { accounts: [...] } and returns per-domain MX/SPF/DKIM/DMARC. client.mjs tags each endpoint [verified] / [ported].
• The 5 write tools (create_campaign, add_leads, mark_thread_read, activate_campaign, reply_to_email) are not exercised by the smoke test — they create/send. list_leads_in_campaign shares the /leads/list path with add_leads and is verified, but confirm the add shape on your first real use.
• This repo does the querying; the salesintel app still owns durable infra (webhooks, reply polling, warmup ramp). Two views on one Instantly account, not two sources of truth.