mcp-x

An MCP server that gives an LLM the X (Twitter) API: read and search posts, manage users and lists, upload media, and publish — as the account whose keys it runs on.

Website · Costs · Credentials · Tools · Quick start · Configuration · Architecture · Contributing

What it is

mcp-x is a Model Context Protocol server written in Go. It exposes the X API v2 to any MCP-compatible client (Claude Desktop, IDE agents, custom LLM apps) as 42 tools covering posts, users, lists and media.

It authenticates with OAuth 1.0a user context, which means every call acts as a real X account — the one the four keys belong to. x_post_create publishes publicly. x_user_follow really follows. x_post_delete is irreversible. This is not a sandbox, and it is not free: see The X API costs money before you wire it into an agent.

Both transports the MCP SDK supports are available and expose the identical tool set:

• stdio — the client launches the binary and talks over stdin/stdout (the default, ideal for desktop clients).
• http — a long-running streamable HTTP server (useful for remote/shared deployments).

The X API costs money

[!WARNING] There is no free tier any more. X retired the Free/Basic/Pro subscription tiers for new developers and moved to pay-per-use credits: you buy credits upfront in the Developer Console and every request deducts from the balance in real time. Legacy Basic ($200/mo) and Pro ($5,000/mo) subscriptions survive only for accounts that already had them; Enterprise starts around $42,000/mo. A new developer account today gets pay-per-use and nothing else.

Rates at the time of writing (official pricing — always re-check the Console, they have changed several times in 2026):

Two things follow from this, and both are baked into the server:

• Reads are charged per resource returned, not per request. max_results: 100 on x_posts_search costs twenty times what max_results: 5 costs for the same query. Every read tool's description tells the model to ask for the smallest max_results that answers the question, and the batching tools (x_posts_lookup, x_users_lookup) tell it to batch rather than loop.
• x_posts_count does not consume the post-read budget. It returns match counts bucketed by minute/hour/day for the same query syntax. Size a topic with x_posts_count first, then pay for x_posts_search.

X also deduplicates: the same resource fetched twice inside a 24-hour UTC window is billed once. And pay-per-use is capped at 3 million post reads per billing cycle — past that, only Enterprise.

When the money runs out the API answers with a distinct error, and the server maps it to a message that explicitly tells the model not to retry — see Errors.

Credentials

The server needs four OAuth 1.0a values, all from one X app:

X_API_KEY
X_API_KEY_SECRET
X_ACCESS_TOKEN
X_ACCESS_TOKEN_SECRET

The first pair identifies the app; the second pair identifies the account acting through it. mcp-x uses AuthenMethodOAuth1UserContext, not app-only bearer auth, because every write endpoint and every "me" endpoint (x_users_me, x_posts_home, x_bookmarks_list, mentions) requires a user context. There is no bearer-token mode.

Getting them — and the one step everybody gets wrong

1. Go to developer.x.com → your project → your app.
2. Open User authentication settings and set App permissions to Read and Write. Do this first.
3. Only then go to Keys and tokens and generate the Access Token and Secret.

[!IMPORTANT] An access token permanently keeps the permissions the app had at the moment it was generated. If you created the token while the app was Read-only and then flipped the app to Read and Write, the token is still read-only. Nothing about the app settings page will tell you this. Every write will fail with X's oauth1-permissions problem type, forever, until you go back to Keys and tokens and regenerate the Access Token and Secret.

This is the single most common setup failure with the X API, which is why the server checks for it at startup and refuses to start with:

Code

Copy

the access token is read-only: set the app permissions to Read and Write
in the X Developer Console, then regenerate the Access Token and Secret

Regenerating the API Key/Secret is not the fix. Regenerate the Access Token and Secret.

Startup verification

Before registering a single tool, the server calls GET /2/users/me once (client.Bootstrap) with a 15-second deadline. This does three jobs:

• proves the four keys are valid — bad keys fail the process, not the first tool call;
• catches the read-only-token trap above;
• caches the key owner's numeric user id, because every write endpoint is POST /2/users/:id/... and looking the id up per write would be another billed request.

A failure here is fatal by design. A server that starts and then fails every call is worse than one that does not start.

The cost of that choice is worth stating plainly: there is no way to try this server without a funded X developer account. No credentials means no startup, which means no tool list — /mcp and claude mcp list will show a failed connection and nothing else. To confirm an install short of that, run the binary with -version, and read the Tools section for what it would have exposed.

Keys are secrets

The four values are credentials for a live account with write access. Keep them in a file only you can read, pass it with -env, and never commit it — .env is gitignored, .env.example is the template. When running under an MCP client, the client's env block works too; it takes precedence over the .env file.

Tools

42 tools in four groups. Every tool carries MCP annotations: readOnlyHint on reads, destructiveHint on anything irreversible (x_post_delete, x_list_delete, unlike, unrepost, unfollow, member removal). Each returns a structured JSON payload matching its output schema; the SDK mirrors the same JSON into the text content block for clients that do not read structuredContent.

Every tool accepts an optional timeout_ms, clamped into the group's [MIN, MAX] window (see Limits).

Posts — reading

x_posts_search

Query operators go inside the query string: