Instantly MCP server

Ein MCP-Server, der Ihren Instantly.ai-Cold-Email-Arbeitsbereich vor einen KI-Client stellt. Fragen Sie Claude nach der Antwortrate der letzten Woche, laden Sie angereicherte Leads in eine Kampagne, sichten Sie die Unibox, pausieren Sie ein Postfach, das seinen Ruf verbrennt – 40 Tools über die Instantly-v2-API.

Der Kern des Projekts ist das Sicherheitsmodell. Jeder Schreibvorgang ist hinter einem expliziten confirm abgesichert, Autonomie ist eine abgestufte Richtlinie mit Volumenlimits und einer Hard-Block-Liste, und alles ist im Code erzwungen – nicht in einem Prompt erbeten. Ein Agent kann sich nicht an einem Limit vorbeireden, denn das Limit ist eine if-Anweisung.

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

Die Vorschau kostet null HTTP-Aufrufe, sodass nichts Instantly erreicht, bis Sie es sagen.

• Transport: standardmäßig lokales stdio – kein Hosting, keine öffentliche URL, kein Token. Eine Umgebungsvariable wechselt zu gehostetem HTTP/SSE (Hosting).

• Auth: Ihr Instantly-v2-Schlüssel, gelesen aus INSTANTLY_API_KEY, niemals hartcodiert und niemals protokolliert.

• Verifiziert: Pfade und Payload-Formen gegen die Live-v2-Referenz geprüft; jede Stelle, an der sich die echte API von der offensichtlichen Vermutung unterscheidet, ist dokumentiert.

• Getestet: Die Suite ist vollständig gemockt und berührt niemals die Live-API.

Schnellstart

Erfordert Python 3.11+ und ein Instantly-Konto mit v2-API-Zugriff.

1. Installation

git clone https://github.com/katekruger/instantlymcp.git
cd instantlymcp

# Option A — uv (preferred)
uv sync

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

2. API-Schlüssel erhalten

Gehen Sie in Instantly zu Einstellungen → Integrationen → API und erstellen Sie einen v2-Schlüssel. Instantly unterstützt bereichsbezogene Schlüssel – beginnen Sie mit einem schreibgeschützten Schlüssel, um Analysen sicher auszuprobieren, und erweitern Sie die Berechtigungen, sobald Sie ihm vertrauen.

export INSTANTLY_API_KEY=your_key_here

3. Start prüfen

# 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

Es wird kein HTTP-Aufruf getätigt, bis ein Tool tatsächlich aufgerufen wird. Mit Strg-C beenden.

4. Bei Ihrem MCP-Client registrieren

Fügen Sie dies zu Ihrer Client-Konfiguration hinzu und passen Sie den absoluten Pfad an:

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

Wenn Sie mit venv + pip statt uv installiert haben, zeigen Sie mit command auf den Einstiegspunkt des venv und entfernen Sie args:

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

Wo diese Konfiguration liegt (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/instantlymcp run instantly-mcp

5. Ausprobieren

Starten Sie den Client neu, bestätigen Sie, dass die instantly-Tools erscheinen, und beginnen Sie mit einem Lesezugriff: „liste meine Instantly-Kampagnen auf". Dann versuchen Sie einen Schreibzugriff – Sie erhalten zuerst eine Vorschau.

Related MCP server: Apollo.io MCP Server

Was es kann

40 Tools. Lesezugriffe laufen frei; Schreibzugriffe sind abgestuft. Vollständige Signaturen und Stufen finden Sie in der Tool-Referenz.

Vier davon sind hart blockiert – delete_lead, delete_webhook, pause_account, remove_from_blocklist – und laufen niemals ohne confirm=true, auf keiner Autonomiestufe, egal was die Richtlinie sagt.

Das Sicherheitsmodell

Zusätzlich zu den Stufen: Volumenlimits pro Aufruf und rollierend über 24 Stunden (Leads, E-Mails, Kampagnen), optionale Kampagnen-Allow-/Deny-Listen und ein append-only audit.log jedes ausgeführten Schreibvorgangs mit geschwärzten Geheimnissen. Das Überschreiten eines Limits erzwingt auch bei autonomous eine Vorschau. Details in Sicherheit und Autonomie.

Hosting

Lokales stdio benötigt kein Hosting und ist die richtige Standardeinstellung – es gibt keine Netzwerkexposition, die verteidigt werden muss. Hosten Sie es nur, wenn der Server existieren muss, während Ihr Rechner aus ist, hauptsächlich um Instantly-Webhooks zu empfangen. Über HTTP ist eingehende Authentifizierung Pflicht und der Server fällt geschlossen aus: kein Token, ein Token unter 32 Zeichen oder eine nicht-https-öffentliche URL – dann weigert er sich zu starten. Ein Dockerfile und ein Render-Blueprint sind enthalten. Siehe Hosting.

Dokumentation

Repository-Struktur

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

Entwicklung

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

CI läuft bei jedem Push und Pull-Request gegen Python 3.11, 3.12 und 3.13.

Lizenz

MIT.