X MCP Server

TypeScript Model Context Protocol (MCP)-Server für die offizielle X-API.

Dieses Projekt ermöglicht es MCP-kompatiblen Agents, einschließlich ChatGPT-Agents, sicher über einen lokalen Server, der auf Ihrem eigenen Computer läuft, auf X-Konten zu lesen und dort zu veröffentlichen.

Der Server unterstützt:

• Das Lesen des authentifizierten X-Kontos.

• Das Nachschlagen von X-Nutzern per Benutzername.

• Das Lesen von Beiträgen anhand der ID.

• Das Auflisten der letzten Beiträge eines Nutzers.

• Das Durchsuchen aktueller Beiträge mit der X-Suchsyntax.

• Das Erstellen von Beiträgen und Antworten, wenn der Schreibmodus explizit aktiviert ist.

• Die Auswahl eines anderen X-Kontos pro lokaler Computerinstallation.

• Ausführung über stdio für lokale MCP-Hosts.

• Ausführung über lokales Streamable HTTP für ChatGPT über OpenAI Secure MCP Tunnels.

Projektstatus

Dies ist ein funktionsfähiger MVP.

Implementiert:

• MCP-Server über stdio.

• MCP-Server über Streamable HTTP.

• Offizieller X-API-Client.

• Lokale Multi-Konto-Konfiguration.

• Sicherer read-only-Modus standardmäßig.

• Expliziter read-write-Modus für Veröffentlichungen und Antworten.

• Lokaler OAuth-2.0-Authorization-Code- + PKCE-Helfer für die Reautorisierung von X-Konten.

• Unit-Tests mit Vitest.

• ChatGPT-Verbindungsanleitung über OpenAI Secure MCP Tunnels.

• Anleitung zum Lebenszyklus des lokalen Servers für manuellen und automatischen Start unter Windows.

Related MCP server: X API FastMCP Server

So funktioniert es

Für lokale MCP-Hosts:

MCP host
  -> stdio
  -> x-mcp-server
  -> official X API

Für ChatGPT-Agents:

ChatGPT agent
  -> custom MCP app
  -> OpenAI Secure MCP Tunnel
  -> tunnel-client on your computer
  -> http://127.0.0.1:3001/mcp
  -> x-mcp-server
  -> official X API

Die X-Anmeldedaten bleiben lokal. ChatGPT verbindet sich über den Tunnel mit dem lokalen MCP-Server; es erhält Ihre X-Zugriffstokens nicht.

Verfügbare MCP-Tools

Schreib-Tools sind blockiert, solange X_MCP_MODE=read-write nicht gesetzt ist.

Voraussetzungen

• Node.js 20 oder neuer.

• Ein X-Developer-Konto.

• Eine X-Developer-App mit aktiviertem OAuth 2.0.

• X-Leseberechtigungen (Scopes): tweet.read users.read.

• X-Schreibberechtigung für Veröffentlichungen und Antworten: tweet.write.

• Empfohlener X-Refresh-Scope: offline.access.

• Für ChatGPT: Entwicklermodus aktiviert.

• Für lokale ChatGPT-Verbindungen: ein OpenAI Secure MCP Tunnel und tunnel-client.

Schritt-für-Schritt-Installation

1. Repository klonen

git clone https://github.com/lluisfont/x-mcp-server.git
cd x-mcp-server

Falls Sie das Repository bereits haben:

cd C:\Repos\x-mcp-server
git pull

2. Abhängigkeiten installieren

npm install

3. Lokale Umgebungsdatei erstellen

Copy-Item .env.example .env

Bearbeiten Sie .env lokal.

Committen Sie .env nicht. Sie kann Zugriffstokens, Refresh-Tokens, Client-Secrets und private API-Schlüssel enthalten.

4. Aktives X-Konto konfigurieren

Für ein benanntes lokales Konto:

X_MCP_ACCOUNT=fcbnews2026
X_MCP_MODE=read-only
X_API_BASE_URL=https://api.x.com

X_ACCOUNT_FCBNEWS2026_USER_ACCESS_TOKEN=
X_ACCOUNT_FCBNEWS2026_REFRESH_TOKEN=

Für mehrere Konten auf demselben Computer:

X_MCP_ACCOUNT=fcbnews2026
X_MCP_MODE=read-only

X_ACCOUNT_FCBNEWS2026_USER_ACCESS_TOKEN=
X_ACCOUNT_FCBNEWS2026_REFRESH_TOKEN=

X_ACCOUNT_LLUISFONT_USER_ACCESS_TOKEN=
X_ACCOUNT_LLUISFONT_REFRESH_TOKEN=

X_MCP_ACCOUNT wählt das lokale Profil aus, das von dieser Installation verwendet wird. Verschiedene Computer können unterschiedliche Konten auswählen, ohne den Code zu ändern.

Der bisherige Einzelkonto-Modus wird ebenfalls unterstützt:

X_MCP_ACCOUNT=default
X_USER_ACCESS_TOKEN=

Neue Installationen sollten benannte Konten bevorzugen.

5. Transport wählen

Für lokale MCP-Hosts, die den Prozess direkt starten:

X_MCP_TRANSPORT=stdio

Für ChatGPT über einen lokalen Tunnel:

X_MCP_TRANSPORT=http
X_MCP_HTTP_PORT=3001
X_MCP_HTTP_PATH=/mcp

6. Typprüfungen und Tests ausführen

npm run typecheck
npm test
npm run build

7. MCP-Server starten

Für stdio:

npm run dev

Für lokales HTTP:

npm run dev:http

Der Standard-HTTP-MCP-Endpunkt ist:

http://127.0.0.1:3001/mcp

Health-Check:

Invoke-RestMethod http://127.0.0.1:3001/healthz | ConvertTo-Json -Compress

Erwartete Antwort:

{"ok":true,"transport":"http","activeAccount":"fcbnews2026","mode":"read-only"}

Lebenszyklus des lokalen MCP-Servers

Wenn ChatGPT dieses MCP über einen Tunnel verwendet, müssen zwei lokale Prozesse laufen:

1. The MCP HTTP server
   -> npm run dev:http
   -> http://127.0.0.1:3001/mcp

2. tunnel-client
   -> .\.tools\tunnel-client\tunnel-client.exe run --profile <profile>
   -> OpenAI Secure MCP Tunnel

Wenn einer der Prozesse gestoppt wird, kann ChatGPT die MCP-Tools nicht verwenden.

Manuell starten

Terminal 1:

cd C:\Repos\x-mcp-server
npm run dev:http

Terminal 2:

cd C:\Repos\x-mcp-server
.\.tools\tunnel-client\tunnel-client.exe run --profile x-fcbnews

Lassen Sie beide Terminals geöffnet.

Lokale Verfügbarkeit prüfen

MCP-Server prüfen:

Invoke-RestMethod http://127.0.0.1:3001/healthz | ConvertTo-Json -Compress

Tunnel-Client prüfen:

Invoke-WebRequest http://127.0.0.1:8080/readyz -UseBasicParsing

Der Tunnel-Bereitschaftsendpunkt sollte HTTP 200 zurückgeben.

Manuell beenden

Drücken Sie Ctrl+C in:

• Dem Terminal, in dem npm run dev:http läuft.

• Dem Terminal, in dem tunnel-client run läuft.

Sobald beide gestoppt sind, hat ChatGPT keinen Zugriff mehr auf den lokalen MCP-Server.

Konto oder Sicherheitsmodus ändern

Bearbeiten Sie .env.

Aktives Konto ändern:

X_MCP_ACCOUNT=fcbnews2026

Schreibmodus aktivieren:

X_MCP_MODE=read-write

Zurück in den sicheren read-only-Modus:

X_MCP_MODE=read-only

Starten Sie den MCP-HTTP-Server nach der Änderung von .env neu:

Ctrl+C
npm run dev:http

Der Tunnel kann weiterlaufen, wenn sich der lokale Port und der MCP-Pfad nicht geändert haben.

Automatischer Start bei Windows-Anmeldung

Für einen Computer, der dieses MCP regelmäßig hosten soll, verwenden Sie den Windows-Taskplaner.

Erstellen Sie ein lokales Startskript, zum Beispiel:

C:\Users\<user>\mcp-start\x-fcbnews-start.ps1

Skript:

$repo = "C:\Repos\x-mcp-server"
$profile = "x-fcbnews"

Set-Location $repo

Start-Process powershell.exe -ArgumentList @(
  "-NoExit",
  "-ExecutionPolicy", "Bypass",
  "-Command", "cd `"$repo`"; npm run dev:http"
) -WindowStyle Minimized

Start-Sleep -Seconds 5

Start-Process powershell.exe -ArgumentList @(
  "-NoExit",
  "-ExecutionPolicy", "Bypass",
  "-Command", "cd `"$repo`"; .\.tools\tunnel-client\tunnel-client.exe run --profile $profile"
) -WindowStyle Minimized

Geplante Aufgabe registrieren:

$action = New-ScheduledTaskAction `
  -Execute "powershell.exe" `
  -Argument "-ExecutionPolicy Bypass -File `"C:\Users\<user>\mcp-start\x-fcbnews-start.ps1`""

$trigger = New-ScheduledTaskTrigger -AtLogOn

Register-ScheduledTask `
  -TaskName "X MCP FCBNews2026" `
  -Action $action `
  -Trigger $trigger `
  -Description "Starts the local X MCP server and OpenAI tunnel-client at Windows logon."

Automatischen Start deaktivieren:

Disable-ScheduledTask -TaskName "X MCP FCBNews2026"

Wieder aktivieren:

Enable-ScheduledTask -TaskName "X MCP FCBNews2026"

Löschen:

Unregister-ScheduledTask -TaskName "X MCP FCBNews2026" -Confirm:$false

Vollständige Anleitung zum Lebenszyklus:

docs/local-server-lifecycle.md

Mit ChatGPT verbinden

Ablauf auf hoher Ebene:

1. Run the MCP server over local HTTP.
2. Create a tunnel in OpenAI Platform.
3. Create a local tunnel-client profile pointing to http://127.0.0.1:3001/mcp.
4. Start tunnel-client.
5. Create a custom MCP app in the ChatGPT agent using Connection: Tunnel.
6. Test x_get_active_account or x_get_me before any write operation.

Empfohlene benutzerdefinierte ChatGPT-MCP-Einstellungen:

Connection: Tunnel
Tunnel: <your OpenAI tunnel>
Authentication: No authentication

Verwenden Sie No authentication, wenn der MCP-Server die endgültigen Dienst-Anmeldedaten lokal verwaltet, zum Beispiel über .env.

Vollständige ChatGPT-Einrichtungsanleitung:

docs/chatgpt-mcp-setup.md

X-Konto erneut autorisieren

Konfigurieren Sie die App in X Developer:

OAuth 2.0: Enabled
App permissions: Read and write
Callback URI: http://127.0.0.1:3002/callback
Website URL: http://127.0.0.1:3002

Ausführen:

$env:X_OAUTH_CLIENT_ID = "<OAuth 2.0 Client ID>"
$env:X_MCP_ACCOUNT = "fcbnews2026"
npm run x:oauth

Öffnen Sie die generierte URL, während Sie mit dem gewünschten X-Konto angemeldet sind. Nach der Autorisierung aktualisiert der Helfer .env mit dem Token des ausgewählten Kontos.

Starten Sie den MCP-Server nach der erneuten Autorisierung neu:

npm run dev:http

Dann überprüfen Sie mit:

x_get_active_account

Detaillierte OAuth-Anleitung:

docs/x-oauth.md

Sicherheitsmodell

Der Server startet standardmäßig im read-only-Modus:

X_MCP_MODE=read-only

Schreib-Tools erfordern:

X_MCP_MODE=read-write

Vor dem Veröffentlichen:

• Überprüfen Sie das aktive Konto mit x_get_active_account.

• Bestätigen Sie den genauen Text, der veröffentlicht werden soll.

• Stellen Sie sicher, dass das X-Token tweet.write besitzt.

• Bitten Sie den Agenten, die generierte post_id zurückzugeben.

• Behandeln Sie einen Beitrag erst dann als veröffentlicht, wenn X eine ID zurückgibt.

Skripte

Dokumentation

• docs/project-architecture.md: Projektarchitektur.

• docs/configuration.md: Umgebungsvariablen und Multi-Konto-Einrichtung.

• docs/local-server-lifecycle.md: Start, Stopp und Automatisierung des lokalen MCP-Servers.

• docs/tools.md: MCP-Tools und Nutzungsverträge.

• docs/x-oauth.md: X-OAuth-Reautorisierung.

• docs/development.md: Entwicklungs-, Test- und Änderungsrichtlinien.

• docs/chatgpt-mcp-setup.md: Schritt-für-Schritt-ChatGPT-MCP-Einrichtung.

Betriebssicherheit

• Anmeldedaten außerhalb von Git aufbewahren.

• read-only als Standardmodus beibehalten.

• read-write nur für kontrollierte Workflows aktivieren.

• Das aktive Konto vor dem Veröffentlichen überprüfen.

• Zugriffstokens oder Refresh-Tokens nicht protokollieren.

• Tokens nicht in Chats, Issues, Dokumentationen oder Pull Requests einfügen.

• Automatischen Start im read-write-Modus auf gemeinsam genutzten Computern nicht ausführen.

Lizenz

Es wurde noch keine Open-Source-Lizenz ausgewählt.