Instantly MCP server

Instantly MCP server

An MCP server that puts your Instantly.aicold-email workspace in front of an AI client. Ask Claude for last week's replyrate, load enriched leads into a campaign, triage the Unibox, pause a mailboxthat's burning reputation — 40 tools over the Instantly v2 API.

The point of the project is the safety model. Every write is gated behind anexplicit confirm, autonomy is a tiered policy with volume caps and ahard-block list, and all of it is enforced in code — not asked for in a prompt.An agent cannot talk its way past a cap, because the cap is an if statement.

You:    "Launch the Design Partners campaign."
Claude: → launch_campaign(campaign_id="camp-1")
        ← "Would LAUNCH (activate) campaign camp-1 — it will start sending.
           AUTONOMY_LEVEL=manual — every write needs confirm=true.
           Re-call with confirm=true to execute."
        This will start sending from your mailboxes. Confirm?
You:    "Yes."
Claude: → launch_campaign(campaign_id="camp-1", confirm=true)   ← now it runs

The preview costs zero HTTP calls, so nothing reaches Instantly until you say so.

• Transport: local stdio by default — no hosting, no public URL, no token. One env var switches it to hosted HTTP/SSE (Hosting).
• Auth: your Instantly v2 key, read from INSTANTLY_API_KEY, never hardcoded and never logged.
• Verified: paths and payload shapes checked against the live v2 reference; every place the real API differs from the obvious guess is written down.
• Tested: the suite is fully mocked and never touches the live API.

Quickstart

Requires Python 3.11+ and an Instantly account with v2 API access.

1. Install

git clone https://github.com/katekruger/instantly-mcp.git
cd instantly-mcp

# Option A — uv (preferred)
uv sync

# Option B — venv + pip
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Get an API key

In Instantly, go to Settings → Integrations → API and create a v2 key.Instantly supports scoped keys — start with a read-only key to tryanalytics safely, then widen the scopes once you trust it.

export INSTANTLY_API_KEY=your_key_here

3. Check it starts

# Fails cleanly if the key is unset:
unset INSTANTLY_API_KEY
instantly-mcp        # -> "ERROR: INSTANTLY_API_KEY is not set", exit 1

# Starts (stdio server waits on stdin) with any non-empty key:
INSTANTLY_API_KEY=dummy instantly-mcp

No HTTP call is made until a tool is actually invoked. Ctrl-C to stop.

4. Register it with your MCP client

Add this to your client config, adjusting the absolute path:

{
  "mcpServers": {
    "instantly": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/instantly-mcp", "run", "instantly-mcp"],
      "env": { "INSTANTLY_API_KEY": "your_key_here" }
    }
  }
}

If you installed with venv + pip instead of uv, point command at the venv'sentry point and drop args:

{
  "mcpServers": {
    "instantly": {
      "command": "/absolute/path/to/instantly-mcp/.venv/bin/instantly-mcp",
      "env": { "INSTANTLY_API_KEY": "your_key_here" }
    }
  }
}

Where that config lives (macOS):

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code: claude mcp add instantly -e INSTANTLY_API_KEY=your_key_here -- uv --directory /absolute/path/to/instantly-mcp run instantly-mcp

5. Try it

Restart the client, confirm the instantly tools appear, and start with a read:"list my Instantly campaigns". Then try a write — you'll get a preview first.

What it can do

40 tools. Reads run freely; writes are tiered. Full signatures and tiers in thetool reference.

Four of them are hard-blocked — delete_lead, delete_webhook,pause_account, remove_from_blocklist — and never run without confirm=true,at any autonomy level, no matter what the policy says.

The safety model

On top of the tiers: per-call and rolling-24h volume caps (leads, emails,campaigns), optional campaign allow/deny lists, and an append-only audit.logof every executed write with secrets redacted. Exceeding a cap forces a previeweven at autonomous. Details in Safety and autonomy.

Hosting

Local stdio needs no hosting and is the right default — there is no networkexposure to defend. Host it only when the server must exist while your machineis off, chiefly to receive Instantly webhooks. Over HTTP, inbound auth ismandatory and the server fails closed: no token, a token under 32 chars, ora non-https public URL and it refuses to start. A Dockerfile and a Renderblueprint are included. See Hosting.

Documentation

Repository layout

src/instantly_mcp/
  server.py      MCP server: the 40 tool definitions, login route, transport selection
  client.py      Instantly v2 API client (httpx) — all HTTP lives here
  models.py      Pydantic input models and normalizers
  policy.py      Risk tiers, autonomy levels, volume caps, audit log
  auth.py        Inbound bearer-token auth for HTTP transports; fails closed
  oauth.py       Single-user OAuth authorization server for MCP clients
  formatting.py  Compact, LLM-friendly summaries of raw API responses
tests/           Fully mocked — never hits the live API
docs/            The pages listed above
Dockerfile       Container image for hosted deployment (non-root, reads $PORT)
render.yaml      Render blueprint; secrets are prompted, never committed
.env.example     Annotated template for every supported variable

Development

pytest -q                 # all mocked, no network, no API key needed
ruff check src tests      # lint

CI runs both on every push and pull request against Python 3.11, 3.12 and 3.13.

See also

segment-mcp — a read-first MCPserver for Twilio Segment, built on the same read-only-by-default,risk-tiered safety model this project's policy.py pioneered.

License

MIT.