x-mcp

Ein meinungsstarker MCP-Server zum Betreiben eines X-Kontos mit einem Agenten.

Er ist kein Wrapper um die X-API. Er ist ein kleiner Operator, der vier Dinge weiß, die die API nicht verrät:

1. Wie „For You“ rankt – die Gewichte, Gates und Filter aus Xs Open-Source-Algorithmus (xai-org/x-algorithm) sind in jedes Tool als Leitplanken und Ratschläge eingebaut: Antwortgewicht 5→20 für Gegenseitige, Copy-Link-Teilen 20, Like 0,5; strikt >10s Video; ≤1 @-Erwähnung; kein Engagement-Köder; ≥4h zwischen Originalen; der erste Favorit öffnet das Out-of-Network-Korpus; Sub-1k-Follower-Kaltstart-Lift; 24h/48h-Fenster.

2. Was die Pay-per-Use-API tatsächlich erlaubt – seit 2026 lehnt X unaufgeforderte Antworten ab und hat Follows, Likes und Quote-Posts aus dem Self-Service entfernt. Die Tools tun alles, was erlaubt ist, und übergeben dem Menschen einen One-Tap-Intent-Link für den Rest, dann gleichen sie automatisch ab, was der Mensch getan hat, aus $0,001 eigenen Reads.

3. Was jeder Aufruf kostet – ein lokales Hauptbuch spiegelt Xs Preise pro Ressource wider (mit dem 24h-Dedup), erzwingt ein monatliches Budget und warnt dich vor dem $0,20 „Post mit URL“.

4. Was ein Unternehmen behält – ein Beziehungs-Ledger aller, die interagiert haben (und wem man zurückfolgen sollte), ein Kalender, der deine besten Stunden lernt, ein Markenbuch, das jede Sitzung teilt, eine Ideen-Pipeline und eine Insights/Report-Schleife, damit der Agent nach eigenen Zahlen statt nach Bauchgefühl steuert.

Basiert auf dem MCP TypeScript SDK v2. stdio standardmäßig, Streamable HTTP optional. Keine Laufzeitabhängigkeiten außer dem SDK und zod.

Tools

Ressourcen: x://playbook (die Regeln), x://boundary (was die API erlaubt), x://handoff (live menschliche Warteschlange). Prompt: operate (die Arbeitsschleife).

Related MCP server: X(Twitter) V2 MCP Server

Setup

1. Erstelle eine App unter https://console.x.com → aktiviere OAuth 2.0 → App-Typ Native App (öffentlich, PKCE) oder Automated App/Bot (vertraulich, gibt ein Client-Secret) → füge Redirect-URI http://127.0.0.1:8477/callback hinzu → kopiere die Client-ID (und das Secret, falls vertraulich). Lade etwas Guthaben auf (Pay-per-Use).

2. Konfigurieren – Umgebungsvariablen werden aus der Umgebung oder aus ~/.x-mcp/.env gelesen (niemals aus dem aktuellen Verzeichnis, damit ein feindliches Repo .env dein Token nicht umleiten kann):

   cd x-mcp && npm install && npm run build
   mkdir -p ~/.x-mcp/media && cp .env.example ~/.x-mcp/.env   # set X_CLIENT_ID (+ X_CLIENT_SECRET if confidential)

   Medien, die der Agent hochladen darf, müssen unter ~/.x-mcp/media liegen (oder in den Verzeichnissen in X_MCP_MEDIA_ROOT) – lege dein Demo-Video dort ab.

3. Einmal anmelden (öffnet einen Browser, speichert Tokens in ~/.x-mcp/tokens.json, Modus 0600):

   node dist/bin.js login

4. Mit deinem Agenten verbinden.

   Hermes (~/.hermes/config.yaml):

   mcp_servers:
     x:
       command: node
       args: ["/absolute/path/to/x-mcp/dist/bin.js"]
       env:
         X_CLIENT_ID: "…"
         X_CLIENT_SECRET: "…"          # confidential apps only
         X_MCP_MONTHLY_BUDGET_USD: "25"
         X_MCP_REQUIRE_APPROVAL: "true" # default; keep until you have X's AI-reply approval
       timeout: 180

   Claude Code:

   claude mcp add x -e X_CLIENT_ID=… -e X_MCP_REQUIRE_APPROVAL=true -- node /absolute/path/to/x-mcp/dist/bin.js

   HTTP statt stdio: X_MCP_HTTP_TOKEN=SECRET node dist/bin.js --http --port 8478 → url: http://127.0.0.1:8478/mcp, Header Authorization: Bearer SECRET. Ein Token ist immer erforderlich (eines wird generiert und ausgegeben, wenn du keins setzt); Host/Origin werden gegen localhost geprüft.

5. Führe die Schleife aus. Bitte den Agenten, den operate-Prompt zu verwenden (oder füge ihn ein). Prüfe node dist/bin.js queue auf alles, was auf dich wartet; node dist/bin.js approve --all führt wartende API-Aktionen aus; tippe auf die Intent-Links für die Nur-Mensch-Aktionen und führe handoff(reconcile) aus (oder lass den Agenten es tun), damit sich die Warteschlange selbst leert.

6. Setze tick auf einen Timer (alle 15 Minuten reicht), damit geplante Posts rausgehen, Handoffs abgeglichen werden und Metriken für insights gespeichert werden:

   */15 * * * * cd /absolute/path/to/x-mcp && node dist/bin.js tick >> ~/.x-mcp/tick.log 2>&1

   (Hermes-Benutzer: Ein Cron-Job, der schedule(run_due) + handoff(reconcile) + post_performance aufruft, tut dasselbe.)

Konfiguration (env)

Was abgelehnt wird, und warum

• Zwei oder mehr @-Erwähnungen in einem Beitrag → wird von X in das Echtzeit-LLM-Spam-Scoring geleitet. Gutschriften in eine Antwort setzen.

• „Like if / RT for / tag someone" → SpamHighRecall, keine Ausnahme für irgendwen.

• Ein Video ≤10,0 s → Video-Head ist 0 und der Beitrag wird aus jedem Video-Korpus ausgeschlossen.

• Video + Bild in einem Beitrag → disqualifiziert für die Video-Korpora.

• Ein zweiter Originalbeitrag innerhalb von 4 h → ×0,625 in geteilten Slates; der Cold-Start-Lift wählt einen Beitrag pro Anfrage aus.

• Gleicher Antworttext zweimal → Copypasta-Clustering.

• Antwort auf einen Beitrag, der dich nicht @erwähnt hat → X lehnt ihn ab; du bekommst stattdessen einen Intent-Link.

• Jede Ausgabe über das Monatsbudget hinaus.

Alles Weiche kann mit force: true überschrieben werden — was die Aktion immer in die menschliche Genehmigungswarteschlange leitet; Medien-Roots, das Budget und X' eigene Grenzen können nicht überschrieben werden.

Sicherheitsmodell (kurz)

• Tokens/Zustand liegen in ~/.x-mcp (Verzeichnis 0700, Dateien 0600); der Server und die x-mcp approve-CLI teilen sie sicher (Neu laden vor dem Schreiben, nie einen neueren Token-Satz überschreiben).

• Der Agent kann keine beliebigen Dateien lesen: media_paths müssen unter den Medien-Roots aufgelöst werden; IDs werden als numerische Snowflakes validiert (kein ../-Pfad-Schmuggel in andere Endpunkte).

• Unumkehrbare oder policy-sensible Aktionen (delete_post, jedes force, DMs, Genehmigungsmodus) erfordern eine menschliche Bestätigung in der CLI. delete_post akzeptiert nur Beiträge, von denen dieser Server weiß, dass sie deine sind.

• Text von Drittanbietern in Tool-Ausgaben wird als Daten gekennzeichnet, nicht als Anweisungen. Der HTTP-Modus benötigt ein Bearer-Token und validiert Host/Origin.

Policy-Hinweise, die du lesen solltest

• X' Automatisierungsregeln (April 2026) verlangen vorherige schriftliche Genehmigung für KI-Antwort-Bots, eine automatisierte Antwort pro Nutzerinteraktion, keine doppelten Beiträge, keine Massen-Follows/Likes/DMs und das Automatisiert-Kontolabel (Einstellungen → Dein Konto → Kontoinformationen → Automatisierung). Dieser Server setzt die mechanischen Teile durch; die Genehmigung und das Label musst du selbst einholen und setzen.

• Der Anwendungsfall, den du im Entwicklervertrag eingereicht hast, sollte beschreiben, was der Agent tut (Posten, Lesen eigener Metriken, Nischenrecherche).

Entwicklung

npm test          # rules engine + full server through an in-memory MCP client against a mock X API
npm run typecheck
npm run build

Quellen: X-API-Dokumentation (docs.x.com, gelesen am 19.08.2026: Preise, manage-posts-Einschränkungen, Changelog, media v2, OAuth 2.0) und xai-org/x-algorithm@11a71f8 (home-mixer/params/param.rs, scorers/, filters/, visibility-filtering/, phoenix/, grox/). Siehe docs/FOR_YOU_PLAYBOOK.md im x-algorithm-Klon für die vollständige Recherche mit Datei:Zeilen-Zitaten.

MIT.