MCP-Server für Instagram-Veröffentlichungen

Ein MCP-Server, der einem KI-Agenten acht Werkzeuge gibt, um auf einem Instagram-Business-Konto zu veröffentlichen: Medien hochladen, Beitrag anlegen, Verarbeitungsstatus abfragen, veröffentlichen, kommentieren, Kommentare lesen und beantworten, Kennzahlen abrufen. Er kapselt ausschließlich die Meta Graph API und einen S3-kompatiblen Objektspeicher. Ablaufsteuerung, Zeitplan und Entscheidung, ob überhaupt veröffentlicht wird, bleiben beim aufrufenden Agenten.

Warum es existiert

Instagram nimmt keine Datei entgegen. Die Graph API erwartet eine öffentlich erreichbare URL, von der sie das Medium selbst abholt, und sie veröffentlicht in zwei Schritten: erst einen Container anlegen, dann — nachdem die Verarbeitung auf Instagram-Seite abgeschlossen ist — diesen Container freigeben. Wer das aus einem Agenten heraus tun will, braucht dazwischen einen Medienspeicher und eine Zustandsabfrage.

Dieser Server ist genau diese Zwischenschicht, und mehr nicht. Er entstand als Ersatz für eine Automatisierung über einen Workflow-Dienst, die für den Zweck zu schwer war: Für acht HTTP-Aufrufe braucht es keinen zweiten Dienst mit eigener Oberfläche, eigener Datenhaltung und eigenem Betriebsaufwand.

Related MCP server: Instagram MCP Server

Voraussetzungen

Der Aufwand liegt nicht im Code, sondern in der Freischaltung bei Meta. Realistisch sind das mehrere Stunden.

• Ein Instagram-Konto vom Typ Business (nicht Creator, nicht privat).

• Eine Meta-App mit dem Produkt „Instagram" und den Berechtigungen instagram_business_basic, instagram_business_content_publish und instagram_business_manage_comments.

• Das Instagram-Konto muss in der App als Tester hinterlegt sein, und die Einladung muss zusätzlich in den Instagram-Kontoeinstellungen angenommen werden. Beides ist nötig; eine Seite allein reicht nicht.

• Ein S3-kompatibler Objektspeicher mit öffentlich lesbarem Bucket. Die Standardwerte sind auf Cloudflare R2 zugeschnitten, jeder andere S3-kompatible Dienst funktioniert bei angepasstem Endpunkt.

Installation

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

Danach die .env ausfüllen. Sie liegt neben server.py und wird von dort gelesen; über die Umgebungsvariable INSTAGRAM_MCP_ENV lässt sich ein anderer Pfad setzen, falls die Zugangsdaten zentral verwaltet werden.

Die .env steht in der .gitignore und gehört unter keinen Umständen in ein Repository. Sie enthält ein Token mit vollem Zugriff auf das Konto.

Bei einem MCP-Client registrieren

claude mcp add instagram-publish -- python /pfad/zu/server.py

Der Server spricht stdio und funktioniert mit jedem MCP-fähigen Client, nicht nur mit dem Beispiel oben. Nach der Registrierung stehen die Werkzeuge in einer neuen Sitzung als mcp__instagram-publish__* bereit.

Die Werkzeuge

Der Ablauf

upload_media("kachel.png", "2026-08-29/kachel.png")
    -> https://<bucket>/2026-08-29/kachel.png

create_container(media_url, caption, is_video=False)
    -> "17912345678901234"

get_status("17912345678901234")
    -> "IN_PROGRESS"   … warten …
    -> "FINISHED"

publish_container("17912345678901234")
    -> "18012345678901234"      ab hier öffentlich sichtbar

Für Reels ist is_video=True zu setzen; die Verarbeitung dauert dann spürbar länger, weshalb get_status überhaupt existiert. Ein Container, der zu lange liegen bleibt, geht in EXPIRED über und lässt sich nicht mehr veröffentlichen.

Token erneuern

Das langlebige Zugriffstoken gilt 60 Tage. Die Erneuerung ist die Stelle, an der die Dokumentation von Meta in die Irre führt: Der naheliegende Endpunkt ig_exchange_token ist für den ersten Tausch eines kurzlebigen Tokens gedacht und antwortet auf ein bereits langlebiges Token mit „Session key invalid". Richtig ist:

GET https://graph.instagram.com/refresh_access_token
    ?grant_type=ig_refresh_token
    &access_token=<aktuelles Token>

Das Ergebnis in INSTAGRAM_LONG_LIVED_TOKEN eintragen. Ein Token, das abläuft, ohne erneuert worden zu sein, lässt sich nicht auffrischen — dann ist der komplette Freischaltungsweg noch einmal fällig. Eine Erinnerung einige Tage vor Ablauf ist keine Bequemlichkeit, sondern notwendig.

Grenzen

publish_container ist irreversibel und sofort öffentlich. Es gibt keinen Entwurfszustand und keine Rücknahme über diesen Server. Das Werkzeug gehört hinter eine ausdrückliche menschliche Freigabe und darf nicht in einer automatischen Kette stehen, die ohne Rückfrage durchläuft. Der Beitrag lässt sich danach nur noch von Hand in der App löschen, und auch das nicht rückstandslos.

Das Token ist Vollzugriff auf das Konto. Wer die .env hat, kann veröffentlichen, kommentieren und Kennzahlen lesen. Der Server gibt das Token nie zurück und schreibt es nicht ins Log — die Log-Stufe von httpx wird bewusst hochgesetzt, weil die Bibliothek sonst die vollständige Anfrage-URL samt access_token im Klartext protokolliert. Das ist die einzige Stelle im Code, an der ein Geheimnis auslaufen könnte.

Weiter offen, bewusst:

• Kein Ratenlimit und keine Wiederholung. Läuft man in ein Limit der Graph API, wirft raise_for_status eine Ausnahme, und der aufrufende Agent muss damit umgehen. Für ein bis zwei Beiträge am Tag ist das unkritisch.

• Kein Liken von Kommentaren. Dafür wäre instagram_business_manage_engagement nötig. Diese Berechtigung gibt es auf dem reinen Instagram-Login-Pfad nicht, sie setzt eine verknüpfte Facebook-Seite und den Facebook-Login-Pfad voraus.

• Kommentar-Endpunkte antworten im Entwicklungsmodus leer. get_comments liefert eine leere Liste, obwohl der Beitrag sichtbar Kommentare hat. Das ist kein Fehler im Server: Die App muss dafür auf „Live" geschaltet sein, was Datenschutzerklärung und Nutzungsbedingungen als erreichbare URLs voraussetzt. Diese Stunde Fehlersuche kann man sich sparen.

• mcp[cli] ist auf <2 festgelegt. Der Server ist gegen die 1.x-API geschrieben (FastMCP). In 2.x heißt die Klasse MCPServer, der Import bricht dort. Die Umstellung ist überschaubar, aber nicht gemacht — ohne die Versionsgrenze läuft ein frisch geklontes Repository sofort in einen ModuleNotFoundError.

• Keine Tests. Alle Werkzeuge sprechen mit einer fremden API; ein sinnvoller Test bräuchte einen Doppelgänger für die Graph API. Für den Umfang stand das bisher in keinem Verhältnis.

Lizenz

MIT, siehe LICENSE.