instantly-ai-mcp

Ein MCP-Server für die Instantly.ai v2 REST-API, der kodiert, was die API tatsächlich tut, statt darauf zu vertrauen, was ihre Dokumentation sagt. Jede unten aufgeführte Eigenheit wurde gegen die Live-API reproduziert, nicht aus einem Changelog oder einem Forenbeitrag kopiert, und bleibt überprüft: npm run verify-gotchas testet das Live-Konto auf Abruf erneut und markiert jede Behauptung, deren reales Verhalten von dem hier Dokumentierten abweicht (siehe Warum diese Tabelle maschinell geprüft wird – es ist eine manuelle Prüfung, kein Teil von CI).

Die Stolperfallen

Diese Tabelle ist der Grund, warum das Repository existiert. Jeder Server, der gegen diese API gebaut wird, entdeckt diese Stolperfallen irgendwann auf die harte Tour – normalerweise, indem er auf einen Fehler starrt, der wie das Falsche aussieht. Live erfasst am 2026-08-21; siehe Warum diese Tabelle maschinell geprüft wird dafür, wie sie ehrlich bleibt.

Anmerkungen zu den interessanten Zeilen:

• #3 – die Live-Sonde sendete campaign_ids: [id] und erhielt 5 Leads zurück, alle 5 gehörten zu anderen Kampagnen. Der Parameter wird nicht nur ignoriert, er ist still ein No-op-Filter; der singuläre Parameter campaign ist es, der die Abfrage tatsächlich eingrenzt. list_leads überprüft aus genau diesem Grund das eigene campaign-Feld jedes zurückgegebenen Leads und warnt, statt dem Filter zu vertrauen.

• #4 – dies wurde am 2026-08-17 als HOLDS aufgezeichnet und am 2026-08-21 auf REFUTED umgedreht. ?id= filtert jetzt korrekt die Analysen auf die einzelne Kampagne. Siehe unten, warum diese Umkehrung der ganze Sinn dieses Repos ist.

• #5 – UNVERIFIABLE am 2026-08-17 (es gab keine Entwurfskampagne im Konto, um dagegen zu testen), dann durch die Live-Integrationssuite (INSTANTLY_LIVE_TEST=1) als HOLDS bestätigt, die eine Wegwerf-Entwurfskampagne erstellt und bestätigt, dass das ungefilterte /campaigns/analytics sie auslässt. Das obige HOLDS ist auf diese Weise verifiziert, nicht durch die Nur-Lese-Sonde von verify-gotchas: Diese Sonde gibt UNVERIFIABLE zurück, wenn keine Entwurfskampagne bereits im Konto existiert (sie erstellt nie eine), daher ist zu erwarten, dass sie bei einem Konto ohne Entwurf „konnte nicht erneut prüfen" sagt, nicht dass sie dieser Zeile widerspricht. list_campaigns liest aus diesem Grund von GET /campaigns – dieser Endpunkt enthält Entwürfe.

• #6, #7, #8 sind prinzipiell UNVERIFIABLE durch die Nur-Lese-Sonde, nicht aus Zufall: #6 und #7 würden einen Live-Schreibzugriff erfordern (Erstellen einer Kampagne / eines Webhooks), den das Sondenskript bewusst nie gegen ein echtes Konto ausführt, und #8 ist ein intermittierendes Lese-Konsistenzproblem, das nicht auf Abruf erzwungen werden kann. UNVERIFIABLE ist hier ein echtes, ehrliches Ergebnis – siehe unten.

Warum diese Tabelle maschinell geprüft wird

Eine handgepflegte Liste von Eigenheiten verrottet. Behauptung #4 oben ist der Beweis: Sie wurde am 2026-08-17 als HOLDS aufgezeichnet und vier Tage später, am 2026-08-21, widerlegt, als Instantly offenbar den ?id=-Parameter serverseitig korrigierte. Vier Tage sind kein langer Zeitraum – so schnell kann sich eine undokumentierte API unter einer niedergeschriebenen Annahme bewegen.

npm run verify-gotchas führt die Sonde jeder Behauptung erneut gegen die Live-API aus und gibt eine fünfspaltige Tabelle aus (#, Claim, Verdict, Observed, Last checked) – eine Obermenge der obigen dreispaltigen Zusammenfassung, die die rohen Beweise der Live-Sonde und das Datum ihrer Ausführung enthält. Das ist nicht dieselbe Form wie die obige Tabelle; erwarte keine bytegenaue Übereinstimmung.

Jede Behauptung trägt auch ein dokumentiertes erwartetes Urteil (HOLDS für #1–#3 und #5, REFUTED für #4, UNVERIFIABLE für #6–#8) – den aktuell dokumentierten Zustand, also das, was diese README heute sagt. Das Skript beendet sich nur dann mit einem Nicht-Null-Exit-Code, wenn sich das tatsächliche Urteil einer Sonde wirklich von dieser Erwartung geändert hat (z. B. ein dokumentiertes HOLDS kommt als REFUTED zurück), und gibt genau an, welche Behauptung abgewichen ist und in welche Richtung. Eine erneute Bestätigung einer bereits dokumentierten REFUTED-Behauptung (wie #4) ist keine Abweichung und lässt den Lauf nicht fehlschlagen – nur eine neue Änderung tut das.

UNVERIFIABLE ist ein echtes Ergebnis, das das Skript ehrlich meldet, kein Fehler, den es übertüncht, und es zählt nie als Abweichung in irgendeine Richtung. Einige Behauptungen können wirklich nicht durch eine sichere, nur lesende, nicht destruktive Sonde überprüft werden (siehe #6–#8 oben); das Skript sagt das, statt zu raten oder still zu überspringen. #5 ist der klarste Fall: Sein dokumentiertes HOLDS stammt aus der Live-Integrationssuite, nicht von dieser Sonde, daher wird ein UNVERIFIABLE-Ergebnis der Sonde (aktuell existiert keine Entwurfskampagne) als „konnte nicht erneut prüfen" gemeldet – kein Fehler.

INSTANTLY_API_KEY=your-key npm run verify-gotchas

verify-gotchas wird manuell ausgeführt, nicht in CI eingebunden – siehe .github/workflows/ci.yml, es führt nur build, typecheck und test aus. Das ist eine bewusste Entscheidung, kein Versehen: CI hat keinen Live-API-Schlüssel (das Skript überspringt sich ohne einen sauber selbst, gibt eine Meldung aus und beendet sich mit 0 – siehe den Anfang von scripts/verify-gotchas.ts –, also wäre es dort ohnehin ein stiller No-op), und dieses Skript existiert, um die Lese-Endpunkte eines echten Kontos zu berühren, womit die CI eines Repos unbeaufsichtigt nichts zu tun hat. Führe es lokal gegen dein eigenes Konto aus, wenn du eine frische Lesung möchtest.

Installation

{
  "mcpServers": {
    "instantly": {
      "command": "npx",
      "args": ["-y", "instantly-ai-mcp"],
      "env": { "INSTANTLY_API_KEY": "your-v2-api-key" }
    }
  }
}

Hole einen v2-API-Schlüssel aus dem Instantly-Dashboard unter Einstellungen → Integrationen → API. Erfordert Node 20+.

Das Sicherheitsmodell

Werkzeuge sind in drei Stufen gruppiert, die durch Umgebungsvariablen gesteuert werden. Eine deaktivierte Stufe wird überhaupt nicht beim MCP-Server registriert – ein Modell, das mit diesem Server spricht, kann ein Werkzeug, das es nicht verwenden darf, buchstäblich nicht sehen oder versuchen; dies ist keine Laufzeit-Berechtigungsprüfung, die ein cleverer Prompt umgehen könnte.

Die gefährliche Stufe erfordert absichtlich beide Flags: Das Aktivieren von Routine-Schreibvorgängen (Hochladen von Leads, Blockieren einer Adresse) aktiviert nie still auch Kampagnenaktivierung, Senden oder Löschen. Diese vier Werkzeuge tragen zusätzlich die destructiveHint: true-Annotation von MCP – ein Hinweis, auf den ein konformer Client möglicherweise reagiert (z. B. durch Aufforderung zur Bestätigung des Benutzers), selbst wenn die Stufe aktiviert ist. Es ist ein client-erzwungenes Verhalten, keine Garantie, die dieser Server gibt: Ein Client, der den Hinweis ignoriert, ruft das Werkzeug ohne zusätzlichen Bestätigungsschritt auf.

Werkzeuge

Lesen (immer registriert)

• list_campaigns – listet jede Kampagne einschließlich Entwürfen auf, mit dekodiertem numerischem Status.

• list_accounts – listet verbundene sendende Postfächer mit Aufwärm-Score, Status und Tageslimit auf.

• campaign_state – prüft den Zustand einer Kampagne über drei unabhängige Endpunkte hinweg und meldet, wo sie abweichen, statt einen Gewinner zu wählen. Die Lead-Listen-Lesung ist seitenbezogen (eine Seite, Limit 100); eine volle Seite wird klar als seitenbegrenzt gemeldet, nie als Instantly-Abweichung.

• list_leads – listet die Leads einer Kampagne, gefiltert nach dem singulären Parameter campaign, mit einer Warnung, wenn das eigene Kampagnenfeld eines zurückgegebenen Leads abweicht. Liest eine Seite (Standardlimit 100); pageLimited im Ergebnis zeigt an, wenn darüber hinaus weitere Leads existieren könnten.

• find_lead – findet einen Lead per E-Mail über den Parameter search; die richtige Zweitmeinung, wenn list_leads falsch aussieht. search ist unscharf, daher wird die Zeile nur zurückgegeben, wenn ihre eigene Adresse mit der angefragten übereinstimmt – eine nahe Übereinstimmung wird als null gemeldet, nie als der Lead.

• list_replies – listet empfangene Antworten mit entferntem zitiertem Thread/Unterschrift und dekodiertem Interessensstatus.

Schreiben (INSTANTLY_MCP_WRITE=1)

• add_leads – lädt Leads in eine Kampagne hoch, verifiziert per Diff (nicht per Anzahl) über zwei unabhängige Lesepfade. Bei einer Kampagne mit mehr als 100 Leads ist auch die Verifikationslesung seitenbegrenzt – die Felder pageLimited und note des Ergebnisses sagen das.

• blocklist_address – blocklistet eine vollständige E-Mail-Adresse; lehnt strukturell nackte Domains ab.

• update_lead – patcht die Felder eines Leads.

• create_campaign – erstellt eine Kampagne als Entwurf (sendet nie); validiert die Zeitzonen-Aufzählung vor jedem Netzwerkaufruf.

• create_webhook – erstellt ein Webhook-Abonnement; validiert die Ereignistyp-Aufzählung vor jedem Netzwerkaufruf.

Gefährlich (INSTANTLY_MCP_WRITE=1 und INSTANTLY_MCP_ALLOW_DANGEROUS=1)

• set_campaign_status – aktiviert oder pausiert eine Kampagne; Aktivieren startet sofort das Senden echter E-Mails.

• send_reply – sendet eine echte, nicht widerrufbare Antwort an einen Lead. Klartext wird für den html-Body HTML-escaped und umbrochen, statt roh eingefügt zu werden; übergib html selbst, um zu überschreiben.

• delete_lead – löscht einen Lead dauerhaft.

• delete_campaign – löscht eine Kampagne und ihre Historie dauerhaft.

Bekannte Einschränkungen

list_replies entfernt den zitierten ursprünglichen Thread und die Signatur aus jeder Antwort (src/reply-text.ts). Es ist bewusst konservativ: Bei mehrdeutiger Eingabe lässt es das Zitat stehen, statt zu riskieren, echten Text zu löschen. Jede verbleibende Randbedingung unten schlägt daher in die SICHERE Richtung fehl – ein zitierter Thread überlebt im zurückgegebenen Text, was Rauschen ist, statt dass ein Satz gelöscht wird, was Datenverlust wäre:

• Eine Zuschreibung, die nur einen Wochentag nennt, z. B. On Tuesday ... wrote:, enthält keines der Datums-/Zeitsignale, die der Entferner benötigt, und wird daher nicht entfernt.

• Eine Zuschreibung, die einen Absender in Kleinbuchstaben ohne Adresse nennt, z. B. ... at 8:22 AM, john wrote:, besteht die Absenderformprüfung nicht (ein echter Absender liest sich als Adresse, ein großgeschriebener Name oder ein Pronomen) und wird nicht entfernt.

• Ein Text, der vollständig eine Signatur ist (-- in der ersten nicht-leeren Zeile, ohne etwas davor), wird vollständig zurückgegeben, einschließlich Trennzeichen, statt geleert zu werden.

Zwei beim Build entdeckte Überstrippings löschten tatsächlich echten Prospect-Text: Ein Textkörper, der mit -- begann, wurde vollständig geleert, und Prosa in der Form On May 5 you wrote: ... wurde fälschlich als Zitat-Thread-Marker gelesen und abgeschnitten. Beide wurden vor der ersten Veröffentlichung behoben und sind durch die Offline-Suite abgedeckt (test/reply-text.test.ts, "Fix round 4").

Es gibt weiterhin kein Tool, das den rohen, ungestrippten body.text einer Antwort zurückgibt. Wenn eine Antwort von list_replies verdächtig kurz erscheint, prüfe sie im Instantly-Dashboard, bevor du daraus schließt, dass der Prospect weniger gesagt hat, als er tatsächlich tat.

Vorherige Arbeiten

Ein bestehendes Paket, instantly-mcp von bcharleson, deckt ein ähnliches Gebiet ab und wurde zuletzt am 2025-06-17 veröffentlicht. Stand 2026-08-21 zeigt sein npm latest-Tag auf 1.0.5, während sein next-Tag 3.0.5-1 trägt – so installiert ein einfaches npx instantly-mcp einen deutlich älteren Build als den neuesten veröffentlichten Code des Pakets (Dist-Tags können sich nach diesem Stand ändern; prüfe erneut npm view instantly-mcp dist-tags für den aktuellen Stand). Dies ist eine sachliche Feststellung, keine Kritik: instantly-ai-mcp ist ein unabhängiges, nicht assoziiertes Projekt mit einem anderen Fokus (die Gotchas-Tabelle und ihre Selbstverifikation) und keine Abspaltung oder ein Ersatz.

Tests

Die Fixture-Suite (npm test) läuft vollständig offline gegen gemockte Clients und benötigt keinen API-Schlüssel. Eine separate Live-Integrationssuite, die hinter INSTANTLY_LIVE_TEST=1 (und einem echten INSTANTLY_API_KEY) liegt, testet die echte API – aber sie erstellt, liest und löscht ausschließlich ihre eigene Wegwerf-Entwurfskampagne (benannt zz-instantly-ai-mcp-throwaway-<timestamp>), niemals eine bestehende Kampagne oder einen bestehenden Lead, und aktiviert oder sendet nichts. Sie überspringt sich selbst, wann immer das Flag oder der Schlüssel fehlt, was in CI immer der Fall ist.

Lizenz

MIT