# instantly-mcp

A **local stdio MCP server** that exposes the [Instantly.ai](https://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

```bash
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):

```bash
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:

```bash
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.