threads-mcp

Ein MCP-Server für die Threads API. Er macht nur Plattform-I/O und sonst nichts: einen Beitrag veröffentlichen, die eigenen Beiträge lesen, deren Insights abrufen, das Veröffentlichungskontingent prüfen. Keine redaktionelle Logik, kein Zeitplan, keine Meinung darüber, was du schreiben solltest.

Es ist der Baustein, den ein Agent braucht, um Threads zu erreichen. Was du postest, ist dein Problem.

npx -y @andreaselmi/threads-mcp    # needs THREADS_ACCESS_TOKEN in the environment

• Schnellstart

• Werkzeuge

• Zugriffstoken erhalten

• Einbindung in einen Client

• Fehlerbehebung

• Was es bewusst nicht tut

• Entwicklung

Schnellstart

Erfordert Node 20 oder neuer. Du musst nichts installieren: MCP-Clients starten den Server mit npx, das ihn bei der ersten Verwendung herunterlädt.

1. Hol dir ein langlebiges Zugriffstoken – komplette Anleitung unten. Das ist der einzige wirklich knifflige Teil, und es ist Metas Schuld, nicht die dieses Pakets.

2. Exportiere es in der Shell, aus der du deinen MCP-Client startest:

export THREADS_ACCESS_TOKEN="THQ..."

3. Füge den Server zur MCP-Konfiguration deines Clients hinzu:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"]
    }
  }
}

4. Starte den Client neu und frag ihn, wer du bist. Er sollte threads_whoami aufrufen und mit deinem Benutzernamen antworten.

Um zu prüfen, ob der Server funktioniert, bevor du überhaupt einen Client einbeziehst:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | npx -y @andreaselmi/threads-mcp

Eine JSON-Zeile mit threads-mcp bedeutet, dass er gestartet ist und dein Token gelesen hat. Eine Fehlermeldung auf stderr verrät dir, was fehlt.

Related MCP server: meta-threads-mcp

Werkzeuge

Die beiden Veröffentlichungs-Werkzeuge sind mit destructiveHint: true markiert; alles andere ist readOnlyHint. Clients, die vor destruktiven Werkzeugen um Bestätigung fragen, fragen auch vor diesen – und das sollten sie auch: Ein veröffentlichter Beitrag geht sofort live, und die API kann ihn weder bearbeiten noch löschen. Zum Entfernen muss man die Threads-App öffnen.

threads_post_insights liest Insights nur für deine eigenen Beiträge und benötigt den Scope threads_manage_insights. threads_publishing_limit meldet das rollierende 24-Stunden-Kontingent, das standardmäßig 250 Beiträge pro Konto beträgt.

Warum es threads_publish_container gibt

Das Veröffentlichen auf Threads besteht aus zwei Aufrufen: Zuerst erstellt man einen Container, dann veröffentlicht man ihn. Wenn der zweite Aufruf fehlschlägt, existiert der Container weiterhin und bleibt 24 Stunden gültig – die gesamte Operation erneut zu versuchen, würde denselben Text zweimal posten. Wenn eine Veröffentlichung fehlschlägt, schreibt dieser Server die Container-ID in die Fehlermeldung; übergib sie an threads_publish_container, um den Vorgang genau einmal abzuschließen.

Der Server wartet außerdem, bis ein Container den Status FINISHED erreicht, bevor er ihn veröffentlicht; er fragt dabei bis zu einer Minute lang alle 2 Sekunden ab, sodass ein langsamer Container nicht fälschlich als Fehler gewertet wird.

Zugriffstoken erhalten

Metas Ablauf hat vier Schritte und keine Abkürzung. Plane beim ersten Mal fünfzehn Minuten ein.

1. Die App erstellen

Geh zu developers.facebook.com/apps und erstelle eine App mit dem Threads-Anwendungsfall. Das Dashboard erzeugt zwei Sätze Anmeldedaten – verwende die Threads-spezifische App-ID und das Secret, nicht die Facebook-Werte. Daran scheitern fast alle.

2. Scopes und einen Tester hinzufügen

Füge unter dem Anwendungsfall Threads die Scopes hinzu, die du benötigst:

Füge dann dein Threads-Konto als Tester hinzu und akzeptiere die Einladung in den Einstellungen dieses Kontos (Konto → Website-Berechtigungen → Einladungen). Bis die Einladung akzeptiert wird, schlägt jeder Aufruf mit einem Berechtigungsfehler fehl, der die Einladung nie erwähnt.

3. Ein kurzlebiges Token erhalten

Öffne das Autorisierungsfenster in einem Browser und ersetze die Platzhalter:

https://threads.net/oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=threads_basic,threads_content_publish,threads_manage_insights
  &response_type=code

Stimme zu, und du landest auf deiner redirect_uri mit angehängtem ?code=.... Die Redirect-URI muss exakt mit einer in den App-Einstellungen registrierten übereinstimmen. Kopiere den Code – er ist nur einmal verwendbar und verfällt in Minuten – und tausche ihn ein:

curl -X POST https://graph.threads.net/oauth/access_token \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -F grant_type=authorization_code \
  -F redirect_uri=YOUR_REDIRECT_URI \
  -F code=THE_CODE_FROM_THE_REDIRECT

Das liefert ein kurzlebiges Token, das eine Stunde gültig ist. Hör hier nicht auf.

4. In ein langlebiges Token eintauschen

curl -G https://graph.threads.net/access_token \
  -d grant_type=th_exchange_token \
  -d client_secret=YOUR_APP_SECRET \
  -d access_token=THE_SHORT_LIVED_TOKEN

Das Ergebnis ist 60 Tage gültig. Das ist der Wert für THREADS_ACCESS_TOKEN.

Das Token am Leben halten

Ein langlebiges Token kann erneuert werden, sobald es mindestens 24 Stunden alt ist und bevor es abläuft. Jede Erneuerung bringt weitere 60 Tage:

curl -G https://graph.threads.net/refresh_access_token \
  -d grant_type=th_refresh_token \
  -d access_token=YOUR_LONG_LIVED_TOKEN

Ein Token, das 60 Tage lang nicht verwendet wird, läuft ab und kann nicht erneuert werden – du beginnst wieder bei Schritt 3. Trag dir eine Erinnerung in den Kalender ein; nichts warnt dich.

Einbindung in einen Client

Umgebungsvariablen

Das Token wird beim Start aus der Umgebung gelesen und nie irgendwohin geschrieben – nicht in eine Datei, nicht in eine Logzeile. Bevorzuge das Exportieren in deiner Shell gegenüber dem Schreiben in eine Konfigurationsdatei: Konfigurationsdateien werden eingecheckt, Shell-Exporte nicht.

Claude Code

claude mcp add threads --scope user -- npx -y @andreaselmi/threads-mcp

Oder committe eine .mcp.json im Wurzelverzeichnis eines Projekts, damit jeder, der daran arbeitet, den Server bekommt:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp@^0.1.0"]
    }
  }
}

Wenn du ^0.1.0 festlegst, erhältst du Fehlerbehebungen, aber keine zukünftige Hauptversion, die die Werkzeuge verändert. Prüfe die Verbindung mit /mcp.

Claude Desktop, Cursor und andere Clients

Gleiche Form, in der Konfigurationsdatei des jeweiligen Clients – claude_desktop_config.json für Claude Desktop, ~/.cursor/mcp.json für Cursor. Clients, die deine Shell-Umgebung nicht erben, müssen das Token explizit übergeben bekommen:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"],
      "env": { "THREADS_ACCESS_TOKEN": "THQ..." }
    }
  }
}

Wenn du das tust, enthält diese Datei nun eine aktive Anmeldeinformation: halte sie aus der Versionskontrolle heraus.

Stattdessen installieren

Wenn du nicht jedes Mal über npx gehen möchtest:

npm install -g @andreaselmi/threads-mcp

Verwende dann "command": "threads-mcp" ohne args.

Fehlerbehebung

Der Server startet nicht / der Client zeigt CONNECTION_CLOSED. Der Prozess wird beim Start beendet, fast immer weil THREADS_ACCESS_TOKEN in der Umgebung, aus der der Client gestartet wurde, nicht gesetzt ist. Das Exportieren in einem Terminal erreicht weder eine bereits laufende App noch eine, die aus dem Dock gestartet wurde. Starte den Server manuell, um die eigentliche Meldung zu sehen:

npx -y @andreaselmi/threads-mcp

Er gibt den Grund aus und beendet sich.

Invalid OAuth access token oder Ähnliches. Das Token ist abgelaufen (60 Tage), oder du verwendest noch das kurzlebige aus Schritt 3. Wiederhole Schritt 4.

Ein Berechtigungsfehler bei einem Aufruf, der funktionieren sollte. Entweder fehlt der Scope – Insights und Veröffentlichung benötigen jeweils ihren eigenen – oder die Tester-Einladung wurde nie aus den Einstellungen des Threads-Kontos akzeptiert.

Post is N characters, the Threads limit is 500. Wird von diesem Server ausgelöst, bevor eine Anfrage gesendet wird; es wurde also nichts veröffentlicht. Teile den Text auf.

Eine Veröffentlichung ist fehlgeschlagen, und du bist nicht sicher, ob sie rausgegangen ist. Lies die Fehlermeldung: Wenn sie eine Container-ID nennt, existiert der Container und der Beitrag ist nicht rausgegangen. Rufe threads_publish_container mit dieser ID auf, anstatt erneut zu veröffentlichen. Wenn sie keine nennt, prüfe threads_list_posts, bevor du es erneut versuchst.

Kontingent erschöpft. threads_publishing_limit zeigt das rollierende 24-Stunden-Fenster – 250 Beiträge pro Konto. Wenn es aufgebraucht ist, wird nichts veröffentlicht, bis Beiträge aus dem Fenster herausfallen.

Was es bewusst nicht tut

Nur Textbeiträge – keine Bilder, Videos, Karussells oder Link-Anhänge. Es liest deine eigenen Beiträge, nicht Antworten, Erwähnungen oder Inhalte anderer. Es plant nichts, wiederholt nichts zeitgesteuert und behält keinen Zustand zwischen Aufrufen: Es hat keine Datenbank und merkt sich nichts.

Es weiß auch nichts darüber, was du postest. Hier leben keine Themen, kein Tonfall, keine redaktionellen Regeln; das gehört zu dem, was es aufruft. Pull-Requests, die produktspezifisches Verhalten hinzufügen, werden gebeten, es in den Aufrufer zu verlagern.

Entwicklung

npm install
npm test          # vitest, no network: fetch is stubbed
npm run dev       # run the server from source over stdio
npm run build     # tsc to dist/

Jeder Test läuft gegen ein gefälschtes fetch, sodass die Suite nie die echte API berührt und kein Token benötigt. Issues und Pull-Requests: github.com/andreaselmi/threads-mcp.

Lizenz

MIT