x-mcp-ai — X (Twitter) MCP Server

An MCP server that exposes the X (Twitter) API v2 to MCP clients — Claude Code, Claude Desktop, VS Code, Cursor, or any MCP-compatible agent — as a curated set of typed tools, gated by a two-axis policy model and aware of the 2026 pay-per-use pricing so an agent can never quietly overspend.

Status: pre-1.0, under active development, published on npm as x-mcp-ai (currently 0.8.0, published from CI with npm provenance). Pin an exact version while the project is on 0.x (Setup). 41 tools across 12 packages are registered today; the full designed surface lives in docs/03-tool-catalog.md and has landed in full. The public API is unstable until 1.0.0.

Contents: Quick demo · Features · Requirements · Setup · Configure credentials · Cost · Run / debug · Develop · Tools · Resources · Prompts · Project structure · Security notes · Data handling · Documentation · Support · Trademark

Quick demo

Once the server is wired into your MCP client, you drive it in natural language and the model picks the tool. Three representative asks:

// 1. Read (default read-only preset — no writes possible)
// "What are people saying about the Model Context Protocol this week?"
{
  "tool": "x_search_recent",
  "arguments": { "query": "\"model context protocol\" -is:retweet lang:en", "max_results": 25 }
}

// 2. Engage (requires the `engage` preset or an explicit write:engagement allow)
// "Like that launch post for me."
{
  "tool": "x_like_set",
  "arguments": { "post_id": "1899…", "action": "like" }
}

// 3. Publish (requires the `publish` preset or write:content)
// "Post: 'Shipping x-mcp-ai today.' — mind the cost."
// Every result carries cost_usd + session_total_usd; a URL in the text raises the price 13×.
{
  "tool": "x_post_create",
  "arguments": { "text": "Shipping x-mcp-ai today." }
}

Features

• 41 tools across 12 packages over the X API v2 — read posts, users and timelines, search (recent and full-archive), engage, publish, manage lists, upload media, walk the social graph, and read/send DMs behind an explicit opt-in.
• Two-axis policy model (operation:domain) with five presets — read-only (default), engage, publish, manage, full. Writes are opt-in; deny beats allow beats preset, per cell. Direct-message cells are double-locked: read:dm/write:dm are in no preset, not even full.
• Cost awareness built in. Since 2026-02-06 the X API v2 is pay-per-use. Every result reports its own cost_usd and the running session_total_usd; an operator-set X_MCP_CREDIT_BUDGET with X_MCP_BUDGET_MODE=hard refuses calls that would exceed it, and the model cannot raise the cap.
• Two auth modes — OAuth 2.0 PKCE user context (primary, rotating refresh tokens, single-flight refresh) and app-only bearer for read-only deployments.
• Security-first defaults — host-scoped Authorization header, redirects never followed on token-bearing requests, 0600 token file written with O_NOFOLLOW/O_EXCL, untrusted-content marking on returned text, and media upload default-deny outside a realpath-contained X_MCP_MEDIA_DIR.
• Typed failures. Eleven error classes, each carrying retryable and fix: "agent" | "operator", so the model retries what is retryable and escalates what is not.
• Structured output. Every tool advertises a JSON-Schema outputSchema and returns structuredContent alongside the text block.
• Availability class-gating, live per-endpoint rate-limit tracking (including the 24-hour app cap on post creation), cursor pagination, and compact result rendering.

Requirements

• Node.js >= 22 (see .nvmrc).
• An X developer account and app with an OAuth 2.0 client (Client ID; Client Secret only for confidential clients). App-only mode needs a bearer token instead.
• Prepaid X API credits — the API bills per read and per write (see Cost).

Setup

The recommended install is the published package, pinned to an exact version while the project is on 0.x — nothing to clone or build:

npx -y x-mcp-ai@0.8.0 doctor   # sanity check; makes no billable calls

Then point your MCP client at it:

// claude_desktop_config.json (Claude Desktop) / .mcp.json (Claude Code) / .cursor/mcp.json
{
  "mcpServers": {
    "x": {
      "command": "npx",
      "args": ["-y", "x-mcp-ai@0.8.0"],
      "env": {
        "X_MCP_AUTH_MODE": "oauth2",
        "X_MCP_CLIENT_ID": "your-oauth2-client-id",
        "X_MCP_POLICY": "read-only",
        "X_MCP_CREDIT_BUDGET": "5.00",
        "X_MCP_BUDGET_MODE": "hard"
      }
    }
  }
}

Running from a local checkout instead? Use "command": "node" with "args": ["/abs/path/to/x-mcp/build/src/index.js"] and the same env map.

Claude Code from the CLI:

claude mcp add x --env X_MCP_POLICY=read-only -- npx -y x-mcp-ai@0.8.0

Per-client instructions — Claude Desktop, Claude Code, VS Code (.vscode/mcp.json), Cursor and MCP Inspector — are in docs/10-operator-guide.md §4, together with the authorize flow and ready-made env recipes.

From source (development)

Still fully supported — build the entry point and spawn it with node instead of npx:

git clone https://github.com/IvanBBaev/x-mcp.git
cd x-mcp
npm ci
npm run build          # tsc → build/src/index.js
node build/src/index.js doctor   # sanity check; makes no billable calls

Configure credentials

The server never prompts interactively; all configuration comes from environment variables (canonical table: docs/02-architecture.md §4; a starting point: .env.example).

Auth modes (X_MCP_AUTH_MODE):

• oauth2 (default) — OAuth 2.0 with PKCE. Run the one-time authorization flow with the authorize subcommand; tokens land in X_MCP_TOKEN_FILE and are refreshed automatically.
• app-only — application-only bearer token (X_MCP_BEARER_TOKEN); read endpoints only, no user context.

X_MCP_AUTH_MODE=oauth2 X_MCP_CLIENT_ID=… node build/src/index.js authorize

Environment variables

Any other X_MCP_* variable is ignored with a startup warning — that is the typo detector. Every fatal configuration error names the variable at fault.

Two-axis access policy

Every tool maps to one policy cell — an operation:domain pair. Operations escalate read → write → destructive; domains are content, user, account, engagement, social-graph, moderation, dm. A preset unlocks a set of the 12 valid cells; X_MCP_POLICY_ALLOW adds cells, X_MCP_POLICY_DENY removes them, and deny > allow > preset.