instagram-mcp

Ein entfernter MCP-Server, der jedem Teammitglied erlaubt, Instagram-Karussells und einzelne Bilder direkt aus einer Claude-Unterhaltung zu veröffentlichen – auf das eigene professionelle Instagram-Konto und niemanden sonst.

Das Bearer-Token identifiziert die Person. Die Person ist genau einem Instagram-Konto in der Datenbank zugeordnet. Kein Tool nimmt jemals eine Instagram-Konto-ID als Parameter, sodass das Posten auf das Konto eines Teammitglieds durch Übergabe der falschen ID strukturell unmöglich ist.

Die Meta-App läuft im Entwicklungsmodus, wobei jedes Teammitglied als Instagram-Tester hinzugefügt wird – keine Meta-App-Prüfung, kein OAuth-Login-Ablauf, kein Live-Gehen. Das ist beabsichtigt.

Verbinde es mit Claude (diesen Abschnitt unverändert an ein Teammitglied senden)

Du benötigst zwei Dinge vom Admin: die Server-URL und dein persönliches Zugriffstoken (beginnt mit igmcp_). Behandle das Token wie ein Passwort – jeder, der es besitzt, kann auf dein Instagram-Konto posten.

1. Öffne in Claude Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen.

2. Füge diese URL ein:

   https://YOUR-DEPLOYMENT.vercel.app/api/mcp

   (der Admin gibt dir den echten Hostnamen)

3. Wo der Connector nach Authentifizierung fragt, füge diesen Header hinzu – Name links, Wert rechts:

   Authorization: Bearer igmcp_your_token_here

   Header-Name: Authorization. Header-Wert: das Wort Bearer, ein Leerzeichen, dann dein Token. Sonst nichts.

4. Speichern. In jeder Unterhaltung kannst du jetzt Dinge sagen wie "Veröffentliche diese 5 Folien als Karussell mit dieser Bildunterschrift" und Claude wird die Bilder hochladen und auf dein Konto posten.

Was du Claude bitten kannst:

• Ein Karussell veröffentlichen (2–10 Bilder, eine Bildunterschrift für den gesamten Beitrag)

• Ein einzelnes Bild veröffentlichen

• Überprüfen, wie viele Beiträge du heute noch hast (Instagram begrenzt die API-Veröffentlichung auf 100 pro 24h)

• Überprüfen deiner Token-Gesundheit (deine Instagram-Verbindung erneuert sich automatisch lange vor Ablauf; dies zeigt dir, ob etwas nicht stimmt)

• Auflisten deiner letzten Beiträge (immer nur deine)

Wenn eine Veröffentlichung auf halbem Weg fehlschlägt, bitte Claude einfach, die gleiche Veröffentlichung erneut zu versuchen – der Server setzt an der Stelle fort, an der er aufgehört hat, und wird nicht doppelt posten.

Onboarding eines neuen Teammitglieds (Admin)

Voraussetzungen, einmal pro Person:

1. Ihr Instagram-Konto muss ein professionelles Konto sein (Business oder Creator).

2. Öffne auf developers.facebook.com die Meta-App → Instagram → API-Setup mit Instagram-Login → füge ihr Konto als Instagram-Tester hinzu. Sie müssen die Einladung annehmen (Instagram-App → Einstellungen → Website-Berechtigungen → Apps und Websites → Tester-Einladungen).

3. Generiere ein langlebiges Zugriffstoken für ihr Konto über das App-Dashboard (der "Token generieren"-Button neben dem Tester-Konto). Kopiere das Token und notiere die Benutzer-ID des Kontos.

Dann füge sie hinzu (von deinem Rechner aus, in diesem Repository, mit ausgefüllter .env.local):

npm run add-member -- --name "Ada" --ig-user-id 17840000000000000 --ig-username ada.builds
# pastes the long-lived IG token when prompted (kept out of shell history)

Das Skript überprüft das Token live gegen graph.instagram.com, lehnt das Hinzufügen ab, wenn das Token zu einem anderen Konto gehört als der von dir übergebenen ID, und gibt das igmcp_-Bearer-Token des Mitglieds einmalig aus. Sende es ihnen über einen sicheren Kanal zusammen mit dem obigen Abschnitt "Verbinde es mit Claude".

Um jemanden zu widerrufen: setze revoked_at = now() in ihrer Zeile in team_members. Ihr Token gibt sofort 401 zurück.

Architektur

instagram-mcp/
├── api/
│   ├── mcp.ts                 # MCP endpoint (Streamable HTTP), bearer auth wrapper
│   └── cron/refresh-tokens.ts # Vercel Cron target (daily; refreshes tokens nearing expiry)
├── src/
│   ├── auth.ts                # bearer lookup → resolves the calling member
│   ├── crypto.ts              # AES-256-GCM for IG tokens, SHA-256 for bearer hashes
│   ├── instagram.ts           # containers, polling, publish, refresh, idempotent resume
│   ├── storage.ts             # R2 uploads (per-member key prefix)
│   ├── db.ts                  # Supabase (service role)
│   ├── refresh.ts             # refresh loop shared by cron + CLI
│   └── tools/                 # one file per tool
├── scripts/
│   ├── add-member.ts          # seeds a member, generates their bearer token
│   └── refresh-tokens.ts      # manual run of the refresh loop
├── supabase/migrations/       # schema (already applied via the Supabase connector)
├── .env.example               # every key, documented
└── README.md

Wichtige Entscheidungen:

• Transport: mcp-handler v2 (Vercels MCP-Adapter) mit @modelcontextprotocol/server v2 – nur Streamable HTTP; der veraltete HTTP+SSE-Transport wurde in v2 upstream entfernt, was genau das ist, was wir wollen. Kein selbstgebauter Transport.

• Host: alles kommuniziert mit https://graph.instagram.com (Instagram-Login-Pfad). graph.facebook.com gehört zum Facebook-Login-Pfad und schlägt mit einem irreführenden Token-Parse-Fehler fehl – die meisten Tutorials machen das falsch.

• Auth: Authorization: Bearer <token> bei jeder Anfrage. Das Token wird gehasht (SHA-256), nachgeschlagen und mit einem konstanten Zeitvergleich erneut überprüft; unbekannte und widerrufene Token erhalten 401, bevor eine Verarbeitung stattfindet. Instagram-Token liegen AES-256-GCM-verschlüsselt in Postgres; Bearer-Token werden niemals roh gespeichert.

• Idempotenz: der Idempotenzschlüssel (Mitglied + Bild-URLs + Bildunterschrift) wird vor jedem Meta-Aufruf in posts geschrieben. Untergeordnete Container-IDs werden beim Erstellen persistent gespeichert. Ein Wiederholungsversuch verwendet FINISHED-Kinder wieder, erstellt nur EXPBRED​ERRORed-Kinder neu, und die erneute Veröffentlichung derselben übergeordneten Container-ID ist sicher (media_publish ist pro Container idempotent) – so kann ein halb veröffentlichtes Karussell niemals dupliziert werden.

• Token-Aktualisierung: Vercel Cron läuft täglich; Token halten 60 Tage und jedes wird erneuert, sobald es in ein 25-tägiges Erneuerungsfenster eintritt, sodass ein fehlgeschlagener Lauf alle 24 Stunden eine neue Wiederholung erhält, anstatt nur einen Versuch pro Monat. Ein fehlschlagendes Mitglied bricht die Schleife nie ab; dauerhafte Fehler (widerrufener Zugriff, Kontoartänderung) markieren die Zeile und werden über check_token_health gemeldet, anstatt endlos wiederholt zu werden.

Bereitstellen (Admin)

npm install
npm run typecheck && npm test     # 19 unit tests, live tests skip without creds

vercel login
vercel link                        # or create the project
# Set every var from .env.example in Vercel → Project → Settings → Environment Variables
vercel --prod

Dann setze die Bereitstellungs-URL in den obigen Abschnitt "Verbinde es mit Claude" ein.

Supabase muss ein dediziertes Projekt sein, das nur diesen Server hostet – kein Projekt, das mit einer anderen App geteilt wird. team_members und posts sind generische Namen und der Service-Role-Client hat vollen Tabellenzugriff, daher ist das Teilen eines Schemas mit einem nicht verwandten Produkt ein Kollisions- (und Schadensradius-) Risiko. Erstelle das Projekt unter deinem eigenen Konto und wende dann die Migration in supabase/migrations/ über den SQL-Editor oder den Supabase-MCP-Connector an.

R2-Bucket benötigt öffentlichen Zugriff (eigene Domain oder r2.dev), der mit R2_PUBLIC_BASE_URL übereinstimmt.

Live-Akzeptanztests

Mit ausgefüllter .env.local und mindestens einem hinzugefügten Mitglied:

LIVE_MEMBER_BEARER_TOKEN=igmcp_...            npm test   # upload + token health, no posting
LIVE_MEMBER_BEARER_TOKEN=igmcp_... LIVE_PUBLISH=1 npm test   # ⚠ creates REAL posts
# add LIVE_MEMBER_BEARER_TOKEN_2=igmcp_... for the two-members-two-accounts test

Betriebshinweise

• Stiller Fehlermodus Nr. 1 ist ein abgelaufenes Token – das Posten stoppt und niemand bemerkt es. Der Cron markiert Fehler lautstark (nicht-200 → roter Lauf im Vercel-Dashboard) und check_token_health meldet Tage bis zum Ablauf und Aktualisierungsfehler pro Mitglied.

• Instagram begrenzt die Veröffentlichung auf 100 Beiträge pro Konto pro rollierender 24h; get_publishing_limit liest den Live-Zähler.

• Container laufen nach ~24h ab und es gibt eine Obergrenze von ~50 ausstehenden Containern pro Konto – ein weiterer Grund, warum der Wiederholungspfad Container wiederverwendet, anstatt neue zu erstellen.

• Behalte Karussell-Folien im gleichen Seitenverhältnis; Instagram beschneidet alles, um zur ersten Folie zu passen. Nur JPEG/PNG, ≤ 8 MB.