X MCP AI

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.

DM cells are never in a preset — not even `full`. read:dm and write:dm must be

granted explicitly via X_MCP_POLICY_ALLOW (all 41 tools callable). Their unlock hint is

deliberately withheld from policy errors, as it is for every other sensitive cell.

Denied tools stay registered but annotated (disabled by policy ) unless

X_MCP_HIDE_DENIED=1.

Note that manage grants destructive content operations only — follow/mute/block need full or an explicit write:social-graph / destructive:social-graph allow.

Cost

Pay-per-use is the only pricing model. X retired the Free/Basic/Pro subscription tiers

for new developers on 2026-02-06; every read and write draws down prepaid credits.

Since 2026-04-16, a post whose text contains a **URL costs $0.20 instead of $0.015 —

13×**. Set X_MCP_CREDIT_BUDGET before pointing an agent at a real account.

Indicative rates (verified 2026-07-22): post reads ~$0.005 each, user lookups and follower/following reads ~$0.010, own-data reads ~$0.001, DM events ~$0.010, post create $0.015 (or $0.20 with a URL), DM send $0.015, list create $0.010, engagement writes currently $0. X also caps post reads at 2,000,000 per month. The authoritative table is docs/01-api-landscape.md §3; the operator's view is docs/10-operator-guide.md §5.

The budget is per process, advisory, resets on restart, and is model-immutable — there is no per-call override and no tool that raises it.

Run / debug

MCP clients spawn the server for you. To run it by hand:

X_MCP_POLICY=read-only node build/src/index.js serve

Command-line interface

|