Instagram Analytics MCP

Ein MCP-Server, der Fragen zur Performance von Instagram-Reels über mehrere Konten hinweg in einfacher Sprache beantwortet.

Es geht nicht darum, eine API zu kapseln. Es geht darum, dass die Kennzahl, die die Reichweite tatsächlich vorhersagt, in der Instagram-API nicht existiert und der Server sie deshalb berechnet.

"How did my last 10 reels do?"
"What worked best this month?"
"Which of my accounts is working?"

Das Problem, das es löst

Die Graph-API von Instagram liefert Aufrufe, Reichweite, Speicherungen, Shares und die durchschnittliche Wiedergabedauer.

Sie liefert keine Abschlussquote – also den Anteil des Videos, den sich die Leute tatsächlich ansehen. Bei einem echten Konto, gemessen über ~700 Reels, ist die Abschlussquote das, was einen Reel, der stirbt, von einem unterscheidet, der sich verbreitet:

Aufrufe sind das Ergebnis. Die Abschlussquote ist die Ursache, und sie ist bereits innerhalb von Stunden nach dem Posten ablesbar, statt erst nach Tagen.

Für die Berechnung braucht es avg_watch_time / duration. Auch die Dauer ist nicht in der API enthalten. Deshalb prüft der Server die media_url jedes Videos mit ffprobe, um sie zu messen.

Genau darum geht es: zwei Schritte, die die API nicht für dich erledigt, und eine bezüglich-Wert-Entscheidung, zu der die API keine Meinung hat.

Tools

Jeder Reel wird mit Datum, Abschlussquote, einem verdict-Label, Dauer, Aufrufen, Reichweite, Speicherungen, Shares, der ersten Zeile der Bildunterschrift als Aufhänger und einem Permalink zurückgegeben.

Funktioniert mit einem oder mehreren Konten. account ist optional und standardmäßig das zuerst eingerichtete Konto.

Voraussetzungen

• Ein Instagram-Professional-Konto (Unternehmen oder Creator). Privatkonten können die Instagram-API überhaupt nicht verwenden.

• Python 3.10+

• ffprobe (brew install ffmpeg) – ohne dieses gibt es keine Dauer, also keine Abschlussquote.

Setup

git clone https://github.com/sskghub/instagram-analytics-mcp
cd instagram-analytics-mcp

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp .env.example .env

Dann besorge dir ein Token. SETUP.md ist die vollständige Schritt-für-Schritt-Anleitung – etwa 15 Minuten für das erste Konto: Meta-App erstellen, Instagram hinzufügen und Token generieren.

Sobald ein Token in .env steht, prüft das hier alles und nennt dir die Konto-ID, die du zurückschreiben kannst, sodass du nie danach suchen musst:

.venv/bin/python check_setup.py

[  OK  ] mcp package installed
[  OK  ] ffprobe found
[  OK  ] main: token works, account @yourhandle

Bestätige dann, dass echte Daten abgerufen werden und die MCP-Schicht Ende-zu-Ende funktioniert:

.venv/bin/python server.py --selftest
.venv/bin/python test_server.py

Registriere das Tool bei Claude Code:

claude mcp add ig-analytics -- /absolute/path/.venv/bin/python /absolute/path/server.py

Der Server liest seine eigene .env, weshalb keine Zugangsdaten in die MCP-Konfigurationsdatei kommen. Diese Konfiguration wird eingecheckt; Tokens nicht.

Ein weiteres Konto hinzuzufügen bedeutet, zwei Zeilen in .env zu ergänzen. Es muss kein Code angepasst werden – die Konten werden aus den Variablennamen erkannt.

Token-Verfall

Instagram-Tokens gelten ~60 Tage. Wenn einesлос ist, liefert alles flussabwärts stillschweigend nichts mehr.

refresh_tokens.py tauscht ein noch gültiges Token gegen ein frisches 60-Tag-iges aus:

python refresh_tokens.py --if-older-than 7

Führe es wöchentlich aus. Die Einschränkung, die das Design bestimmt: Ein abgelaufenes Token kann nicht erneuert werden. Meta verlängert ein kaputtes Token nicht, deshalb ist das Erneuern der einzige Weg, der funktioniert. Jede Erneuerung setzt die kompletten 60 Tage neu, also kostet ein frühes Erneuern nichts.

Hinweise zur Planung, damit auch die macOS-Falle klar wird, wo ein launchd-Job deine Dateien gar nicht lesen kann, findet du in SETUP.md.

Es erstellt vor dem Schreiben eine Sicherungskopie von .env, überschreibt doppelte Schlüssel und meldet Fehler.

Das Erneuern macht das alte Token nicht ungültig, sodass mehrere Rechner unabhängig voneinander je ihr eigenes .env aktualisieren können. Token-Werte müssen nie zwischen Hosts abgeglichen werden.

Notizen aus der Entwicklung

Dinge, die echte Zeit gekostet haben, die hier gesammelt sind, weil alle diese Aspekte übertragbar sind.

sys.exit() ist in einer CLI in Ordnung, aber in einem Server tödlich. Die erste Version verwendete eine Funktion aus einem vorhandenen Kommandozeilenskript. Diese Funktion rief sys.exit() auf, wenn ein Token abgelehnt wurde – das hätte den gesamten Serverprozess getötet am Tag, an dem ein Token verfallen wäre. Tools werfen heute eine ValueError; das SDK macht aus regulären Exceptions lesbare Ergebnisse, die das Modell nutzen kann, und der Server überlebt.

Fehler sollten sagen, was zu tun ist. Ein totes Token liefert die Schritte zur Neu-Erzeugung, keinen Stack-StackTrace. Das Modell kann das einem Menschen mitteilen, der es tatsächlich beheben kann.

Der Docstring ist die Schnittstelle. Er ist der Grund, wieso das Modell überhaupt ein Tool aufruft; jede Funktion sagt daher wann man es verwenden soll, nicht nur, was es zurückgibt.

Geplante Aufgaben können stillschweigend scheitern. Auf macOS schlug eine launchd-schreibende ausgradie für das Erneurungsskript mit Operation not gent fehl, weil TCC unter den Background-Agenten das Lesen von geschätzten Ordnern verhindert. Der Job wurde als geladen gemeldet und wäre still und heimlich nie ausgeführt worden. Nur das Erzwingen des Laufs und das Protokoll lesendollend, es anzubieten.

Doppelte Schlüssel in .env sind eine echte Falle. Ein veraltees Duplikat kann ein gerade geschriebenes Token überdecken – auch deren Hand, wie der Ladete die Auflösung vornimt. Deshalb überschreibt der Writer alle Vorkommen, nicht nur das erste.

Die API wurde umbenannt. Dies ist mcp.server.mcpserver.MCPServer; der ältere Pfad mcp.server.fastmcp.FastMCP wurde in mcp 2.x entfernt, zusammen mit anderen Legacy-Modulen. Die meisten Online-Beispiele zeigen einen alten Import und werden nicht mehr laufen.

Lizenz

MIT