mcp-x

<h1 align="center">mcp-x</h1>

<p align="center">
  <b>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.</b>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-8bc34a?style=for-the-badge" alt="License MIT"></a>
  <img src="https://img.shields.io/badge/Go-1.26+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go">
  <img src="https://img.shields.io/badge/MCP-Server-6E56CF?style=for-the-badge&logo=anthropic&logoColor=white" alt="MCP">
  <img src="https://img.shields.io/badge/Transport-stdio_%7C_http-26A5E4?style=for-the-badge" alt="Transport">
  <img src="https://img.shields.io/badge/X_API-v2-000000?style=for-the-badge&logo=x&logoColor=white" alt="X API v2">
  <img src="https://img.shields.io/badge/Auth-OAuth_1.0a-eab308?style=for-the-badge" alt="OAuth 1.0a">
  <img src="https://img.shields.io/badge/Paid_API-pay--per--use-e11d48?style=for-the-badge" alt="Paid API">
</p>

<p align="center">
  <a href="#the-x-api-costs-money">Costs</a> ·
  <a href="#credentials">Credentials</a> ·
  <a href="#tools">Tools</a> ·
  <a href="#quick-start">Quick start</a> ·
  <a href="#configuration">Configuration</a> ·
  <a href="#architecture">Architecture</a> ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

---

## What it is

`mcp-x` is a [Model Context Protocol](https://modelcontextprotocol.io) 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](#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](https://developer.x.com) 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](https://docs.x.com/x-api/getting-started/pricing) — always re-check the Console, they have changed several times in 2026):

| Operation | Price |
| :--- | :--- |
| Post read | **$0.005** per post returned |
| Owned read (your own posts, bookmarks, followers, likes, lists) | **$0.001** per resource |
| User read | **$0.010** per user returned |
| Likes / mutes / blocks read | **$0.001** per resource |
| Followers / following read | **$0.010** per resource |
| **Publishing a post** | **$0.015** per request |
| **Publishing a post containing a URL** | **$0.200** per request |
| Like / repost and other interactions | **$0.015** per request |
| List and bookmark writes | $0.005–$0.010 per request |

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](#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](https://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:
>
> ```
> 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](#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](#limits)).

### Posts — reading

| Tool | Description |
| :--- | :--- |
| **`x_posts_search`** | Searches recent posts for several queries **in parallel**. Recent search reaches back **7 days only**. |
| **`x_posts_count`** | Counts matches per query bucketed by minute/hour/day. **Does not spend post reads** — use it to size a topic before searching. |
| **`x_posts_lookup`** | Fetches up to **100 posts by id** in one call. |
| **`x_posts_by_user`** | Recent posts for several usernames, fetched in parallel. |
| **`x_posts_mentions`** | Posts mentioning the key owner. |
| **`x_posts_home`** | The key owner's home timeline. |
| **`x_posts_quotes`** | Posts quoting a given post. |
| **`x_posts_liked`** | Posts the key owner liked. |
| **`x_bookmarks_list`** | The key owner's bookmarks. |
| **`x_post_liked_by`** | Users who liked a given post. |
| **`x_post_reposted_by`** | Users who reposted a given post. |

#### `x_posts_search`

| Parameter | Type | Default | Notes |
| :--- | :--- | :--- | :--- |
| `queries` | `[]string` | — | **Required.** Run in parallel, capped at `POSTS_MAX_QUERIES` (`5`). ≤ 512 chars each. |
| `max_results` | `int` | `10` | Posts **per query**, 1..100. Every one is billed. |
| `sort_order` | `string` | — | `recency` (newest first) or `relevancy` (best match). |
| `days` | `int` | `7` | How far back, 1..7. The API cannot go further. |
| `include_retweets` | `bool` | `false` | When false the server appends `-is:retweet` to every query. |
| `timeout_ms` | `int64` | `15000` | Whole-call timeout, clamped to `[2000, 60000]`. |

Query operators go **inside the query string**:

| Operator | Meaning |
| :--- | :--- |
| *space* | AND |
| `OR` | explicit OR |
| `-term` | NOT |
| `( )` | grouping |
| `from:user` / `to:user` | by author / by recipient |
| `@user` / `#tag` | mentions / hashtags |
| `"exact