Threads MCP Server

threads-mcp ist ein stdio MCP-Server für die offizielle Threads-API. Er ist so konzipiert, dass er sich eng an die veröffentlichte Meta Threads-Dokumentation hält und gleichzeitig eine praktische MCP-Tool-Oberfläche für Authentifizierung, Veröffentlichung, Lesen, Moderation, Insights, Entdeckung, Standorte und Einrichtungsdiagnosen bietet.

Der aktuelle Build ist absichtlich auf offiziell dokumentierte Threads-Funktionen und die offizielle Postman-Sammlung beschränkt. Er stützt sich nicht auf undokumentierte Fallback-Endpunkte oder Komfort-Wrapper, die in einem öffentlichen Paket schwer zu warten wären.

Highlights

• Nur offizieller Threads-API-Umfang

• MCP-Tools für Authentifizierung, Profilsuche, Veröffentlichung, Lesen, Antworten, Insights, Suche, Standorte, oEmbed und Diagnosen

• Veröffentlichungseingaben in camelCase modelliert und intern in die von Threads erwarteten snake_case-Parameter serialisiert

• Unterstützung für mehrstufige Karussell-Veröffentlichungen

• Gemeinsame Client-Schicht für Wiederholungsversuche, Polling, Paginierung und normalisierte Meta-API-Fehler

Schnellstart

1. Abhängigkeiten installieren:

npm install

2. Server bauen:

npm run build

3. Erstellen Sie Ihre lokale Umgebungsdatei und setzen Sie mindestens THREADS_ACCESS_TOKEN.

4. Wenn Sie noch ein Token benötigen, führen Sie den lokalen OAuth-Helfer aus:

npm run auth:token

5. Starten Sie den Server:

node dist/index.js

6. Rufen Sie validate_setup auf, bevor Sie Veröffentlichungs- oder Moderationsabläufe mit einem echten Konto verwenden.

Tool-Katalog

Authentifizierung

• exchange_code_for_token

• get_long_lived_access_token

• refresh_access_token

• get_app_access_token

Profile und Entdeckung

• get_me

• get_profile

• get_profile_threads

Veröffentlichung und Lebenszyklus

• get_publishing_limit

• create_thread_container

• publish_thread

• create_and_publish_thread

• repost_thread

• delete_thread

Lesen und Antworten

• get_threads

• get_thread

• get_replies

• get_thread_conversation

• get_pending_replies

• manage_reply

• manage_pending_reply

Insights, Suche und Einbettungen

• get_user_insights

• get_thread_insights

• search_threads

• get_mentions

• get_oembed

Standorte und Diagnosen

• search_locations

• get_location

• validate_setup

Explizit außerhalb des Geltungsbereichs für v1

• Webhooks

• Hosting für eingebettete OAuth-Callbacks

• Alle undokumentierten Fallback-Endpunkte oder Komfortfunktionen, die nicht durch die offiziellen Dokumente oder die offizielle Postman-Sammlung abgedeckt sind

Architektur

Der Server ist in einige klare Schichten unterteilt:

• src/index.ts startet den MCP stdio-Transport.

• src/threads/client.ts verwaltet authentifizierte HTTP-Aufrufe, Wiederholungsversuche, Paginierung, Polling und normalisierte Meta-API-Fehler.

• src/tools/ enthält ein Modul pro Tool-Familie sowie gemeinsame Schemata.

Das Veröffentlichungs-Eingabemodell wird als eine einzige öffentliche diskriminierte Union bereitgestellt, die text, image, video, carousel und reply abdeckt.

Voraussetzungen

Sie benötigen all das Folgende, bevor der Server Live-API-Aufrufe tätigen kann:

• Eine Meta-App, die für den Threads-Anwendungsfall konfiguriert ist

• Ein Threads-Benutzerzugriffstoken für das Konto, mit dem Sie arbeiten möchten

• Erweiterter Zugriff und App-Überprüfung, wo Ihre Integration dies erfordert

• Node.js 20+ auf dem Computer, auf dem der Server ausgeführt wird

Umgebungsvariablen

Erforderlich für die meisten Benutzer-Token-Tools:

• THREADS_ACCESS_TOKEN

Optional:

• THREADS_APP_ID

• THREADS_APP_SECRET

• THREADS_REDIRECT_URI

• THREADS_API_BASE_URL

• THREADS_USER_ID

• THREADS_MAX_RETRIES

• THREADS_RETRY_BASE_DELAY_MS

• THREADS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_POLL_INTERVAL_MS

Kopieren Sie .env.example und setzen Sie mindestens das Zugriffstoken. THREADS_APP_ID und THREADS_APP_SECRET werden auch für die Auth-Helfer-Tools und für get_oembed benötigt, wenn Sie kein explizites App-Zugriffstoken übergeben.

Wo Sie THREADS_APP_ID erhalten

• Öffnen Sie Ihre App im Meta for Developers Dashboard: https://developers.facebook.com/apps/

• Öffnen Sie die App, die mit dem Threads-Anwendungsfall erstellt wurde

• Gehen Sie zu Use Cases -> Threads -> Customize -> Settings

• Kopieren Sie die Threads App ID von dieser Seite

• Verwenden Sie diesen Wert als THREADS_APP_ID

Wichtig:

• Verwenden Sie nicht die allgemeine Meta-App-ID aus dem übergeordneten App-Dashboard oder der Einstellungsseite

• Verwenden Sie die Threads-spezifischen Anmeldeinformationen aus Use Cases -> Threads -> Customize -> Settings

THREADS_APP_SECRET stammt von derselben Threads-Einstellungsseite. Halten Sie es privat.

Token-Helfer-Skript

Das Repository enthält einen lokalen OAuth-Helfer, der dem Meta Threads-Zugriffstoken-Ablauf folgt:

1. Öffnen Sie das Threads-Autorisierungsfenster

2. Empfangen Sie den Autorisierungscode über eine lokale Callback-URL

3. Tauschen Sie ihn gegen ein kurzlebiges Token ein

4. Tauschen Sie dieses gegen ein langlebiges Token ein

5. Speichern Sie das Ergebnis in .env als THREADS_ACCESS_TOKEN

Einrichtung:

• Fügen Sie Ihre Meta-App-Anmeldeinformationen zu .env hinzu

• Stellen Sie sicher, dass die gültige OAuth-Redirect-URI Ihrer App mit THREADS_REDIRECT_URI übereinstimmt

Ausführen:

npm run auth:token

Optionale Flags:

• --redirect-uri http://127.0.0.1:8788/callback

• --env-file .env.local

• --no-open

Erforderliche Scopes nach Tool-Familie

• threads_basic Wird von get_me, get_profile, get_threads, get_thread und der grundlegenden Einrichtungsvalidierung verwendet.

• threads_content_publish Wird von get_publishing_limit, create_thread_container, publish_thread und create_and_publish_thread verwendet.

• threads_read_replies Wird von get_replies und sicheren Antwort-Lese-Tests in validate_setup verwendet.

• threads_manage_replies Wird von manage_reply verwendet.

• threads_manage_insights Wird von get_user_insights und get_thread_insights verwendet.

• threads_keyword_search Wird von search_threads verwendet.

• threads_profile_discovery Wird von get_profile und get_profile_threads für Szenarien zur Entdeckung öffentlicher Konten verwendet.

• threads_location_tagging Wird von search_locations, get_location und Veröffentlichungsabläufen verwendet, die locationId setzen.

• threads_delete Wird von delete_thread verwendet.

validate_setup führt sichere Tests durch, um den Zugriff für threads_basic, threads_content_publish, threads_read_replies, threads_manage_insights, threads_keyword_search, threads_profile_discovery und threads_location_tagging abzuleiten. Es führt absichtlich keine destruktiven Tests für threads_manage_replies oder threads_delete durch, daher werden diese Scopes nicht aktiv durch die Einrichtung validiert.

Veröffentlichungsverhalten

Der Server modelliert offizielle Container-Optionen in camelCase und serialisiert sie intern in die snake_case-Parameter, die von der Threads-API erwartet werden.

Unterstützte Eingaben umfassen:

• Allgemeine Felder: text, replyControl, replyToId, quotePostId, topicTag, locationId, textEntities, allowlistedCountryCodes

• Nur-Text-Felder: linkAttachment, pollAttachment, textAttachment, gifAttachment, enableReplyApprovals, autoPublishText, isGhostPost

• Bild- oder Videofelder: imageUrl, videoUrl, altText, isSpoilerMedia

• Karussell-Elemente: validierte Arrays von Bild- oder Videoelementen mit Medienelementen pro Element

Die Karussell-Veröffentlichung folgt dem offiziellen mehrstufigen Ablauf:

1. Erstellen Sie einen Element-Container pro Bild oder Video mit is_carousel_item=true

2. Erstellen Sie den übergeordneten Karussell-Container mit children=[...]

3. Veröffentlichen Sie den übergeordneten Container

Abdeckungshinweise

Das Repository deckt derzeit diese offiziellen Threads-API-Familien ab:

• Autorisierungshelfer

• Veröffentlichung, einschließlich Zitat-Posts, Repost-Veröffentlichung und Container-Status-Polling

• Benutzerprofilsuche und Abruf öffentlicher Profil-Posts

• Abruf von Threads-Medien

• Abruf von Antworten, abgeflachte Konversationen, ausstehende Antworten, Verbergen und Einblenden sowie Genehmigungs- und Ignorier-Abläufe

• Benutzer- und Post-Insights

• Stichwortsuche und Erwähnungen

• Standortsuche und Standortabruf

• oEmbed

• Einrichtungsdiagnosen

Beispiel für lokale MCP-Konfiguration

Beispiel für eine Konfiguration im Claude Desktop-Stil:

{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/absolute/path/to/threads-mcp/dist/index.js"],
      "env": {
        "THREADS_ACCESS_TOKEN": "thdt_your_user_access_token",
        "THREADS_APP_ID": "optional_app_id",
        "THREADS_APP_SECRET": "optional_app_secret"
      }
    }
  }
}

Wenn Sie dieses Paket später als CLI veröffentlichen, kann der command zu threads-mcp werden.

Veröffentlichung

Die Paket-Metadaten sind bereits für die npm-Veröffentlichung als öffentliches Paket konfiguriert:

• Paketname: threads-mcp

• aktuelle Version: 0.0.0

• CLI-Einstiegspunkt: threads-mcp

• Veröffentlichungszugriff: public

Führen Sie vor der Veröffentlichung Folgendes aus:

npm run build
npm test
npm publish --access public

prepublishOnly ist so konfiguriert, dass die Build- und Testschritte automatisch während npm publish ausgeführt werden.

Entwicklung

Installieren Sie die Abhängigkeiten, sobald Node.js verfügbar ist:

npm install
npm run build
npm test

Empfohlene manuelle Prüfungen:

1. Führen Sie npm run build aus, um die TypeScript-Kompilierung zu überprüfen.

2. Führen Sie npm test aus, um die Schema-, Client- und Tool-Registrierungstests auszuführen.

3. Starten Sie den Server mit node dist/index.js.

4. Rufen Sie zuerst validate_setup mit einem echten Token auf.

5. Testen Sie create_thread_container und publish_thread mit einem Test-Threads-Konto.

Bekannte Einschränkungen

• Transport ist in v1 nur stdio

• Es gibt keinen eingebetteten OAuth-Callback-Server; Token-Austausch-Helfer werden stattdessen als MCP-Tools bereitgestellt

• validate_setup kann threads_manage_replies nicht sicher verifizieren, ohne einen zustandsändernden Moderationsaufruf durchzuführen

• validate_setup führt auch keinen zustandsändernden Löschtest durch

• create_and_publish_thread lehnt autoPublishText=true absichtlich ab, da dieses Flag mit dem expliziten zweistufigen Vertrag des Tools in Konflikt steht

• Die Antwort-Veröffentlichung ist als dedizierte reply-Variante modelliert, die durch den offiziellen reply_to_id-Parameter unterstützt wird und derzeit auf Textantworten im öffentlichen Schema abzielt

• Die Überprüfung des Live-API-Verhaltens hängt weiterhin von gültigen App-Anmeldeinformationen, genehmigten Scopes und einem echten Threads-Konto ab

Quellen für API-Umfang und Endpunktauswahl

• Meta Threads API-Referenz: https://developers.facebook.com/docs/threads/reference

• Meta Threads Veröffentlichungsreferenz: https://developers.facebook.com/docs/threads/reference/publishing

• Offizieller Meta Postman-Arbeitsbereich: https://www.postman.com/meta/threads/documentation/dht3nzz/threads-api