X (Twitter) MCP Server: Official Guide 2026

TL;DR + what you actually need

Five facts that shape every decision below:

• It is hosted and first-party. The server runs at https://api.x.com/mcp over Streamable HTTP. Nothing to deploy — X operates it.
• “Without any setup” is marketing. For user context and writes you run a small local bridge, xurl mcp, and you need an X developer app with OAuth 2.0 enabled. Read-only via an app-only Bearer token is genuinely one header.
• It is not free. Every tool call bills against your X API plan or pay-per-use credits. The MCP adds no new pricing — it inherits the X API’s.
• Six capability groups. Posts, search (full-archive, user, news), users and timelines, bookmarks, trends and news by location, and Articles (draft + publish).
• There are two of them. The API server above, plus a second hosted server that answers questions about X’s own API docs.

The fastest read-only test, no browser login, no OAuth — point any client at the URL with an app-only Bearer token:

{
  "url": "https://api.x.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN" }
}

That gets you reads with no user context. The rest of this guide explains the OAuth bridge that unlocks writes, what each tool does, and the cost model you should understand before you connect an agent that can spend.

What the X MCP server actually is

The X MCP server is a hosted MCP endpoint — MCP being the open JSON-RPC standard that lets any LLM client call any tool server (our what-is-MCP explainer covers the protocol itself). Instead of every developer building and hosting their own bridge between an AI client and the X API, X now runs that bridge for you at api.x.com/mcp. The MCP does not add new capabilities; as TechCrunch put it, it “exposes existing X API capabilities — searching posts, reading content, looking up users, and analyzing conversations and trends” to agents that already speak MCP.

The launch landed on June 30, 2026 via @XDevelopers, framed around a single pitch: real-time data. X’s wedge over a GitHub or Notion MCP is that its corpus is the live public conversation, and an agent that can search the full archive and read trends as they form is doing something other connectors cannot. The announcement cleared 2.8 million views in its first day — the developer audience noticed.

The honest framing: this is X turning its API into an agent-native surface, on the same API plan and pricing you already pay. The convenience is real (no middleware, no token plumbing, maintained by the platform). The capability is not new. If you can already call the X API, the MCP is a better-shaped door to the same room.

Hosted vs self-hosted (two things named “X MCP”)

Search “X MCP” and you hit two first-party artifacts with nearly the same name. They are not interchangeable.

The June 30 announcement is about the hosted server. The xdevplatform/xMCP repo is the self-host option — it wraps the X API OpenAPI spec into 175 FastMCP tools and runs on your own box, which you would tunnel through something like ngrok to reach remotely. Most people want the hosted one. Reach for the self-hosted build only when you need to inspect or modify the tool surface, run inside your own network boundary, or pin a specific endpoint set. Either way, the local xurl CLI is the glue.

What it can do: the six tool groups

From X’s MCP documentation, the hosted server exposes its tools across six groups. This is the surface your agent sees in its tool list:

• Posts — fetch posts; list the accounts that liked, reposted, or quoted a post; get recent counts for a query.
• Search — full-archive post search, user search, and news search. The full-archive search is the headline tool: it reaches back across X’s history, not just the recent window.
• Users — resolve the current authenticated user, look up users by ID or handle, and read timelines and mentions.
• Bookmarks — list, add, and remove bookmarks, and manage bookmark folders. (These are writes — see rate limits.)
• Trends & News — trends by location using a WOEID (a Where-On-Earth ID), plus news stories.
• Articles — create draft Articles and publish them. This is long-form publishing straight from an agent, gated behind OAuth.

Coverage reports put the hosted surface north of 200 X API endpoints behind those groups; the open-source xMCP build exposes 175. Either way, the design choice is the same one every large API MCP is converging on — group the API into a manageable tool set rather than emit one tool per endpoint and blow past the client’s tool budget.

Opinionated takeaway: the two tools that justify this server over a generic web-search MCP are full-archive search and trends by WOEID. Those are X-proprietary data an agent cannot get cleanly anywhere else. If your use case does not touch real-time or historical X data specifically, you probably do not need this connector.

Auth model: OAuth 2.0 through the xurl bridge

This is where everyone slows down, so here is the exact shape of it. The hosted endpoint speaks Streamable HTTP and authenticates with a Bearer token. There are two ways to get one in front of it:

1. App-only Bearer token (read-only). Paste your app’s Bearer token into an Authorization header on the MCP client. No bridge, no browser login, no user context. Good for read-only research agents.
2. OAuth 2.0 with PKCE (full access). Required for writes and user-scoped reads. The local xurl mcp command handles the OAuth dance: first run opens a browser to log in, tokens cache in ~/.xurl, and they refresh automatically.

The bridge is the part worth understanding. Per the xurl docs, xurl mcp [URL] “bridges a stdio MCP client to a remote Streamable HTTP MCP server (default https://api.x.com/mcp), injecting Authorization: Bearer <token>” and refreshing it automatically. So from your client’s point of view, the “remote” X server looks like a local stdio server. That is why the configs below say "command": "npx" rather than a plain "url":

  stdio JSON-RPC          HTTPS + Authorization: Bearer
client  <───────────>  xurl mcp  <───────────────────────>  api.x.com/mcp
(Cursor,                (local bridge,                       (hosted,
 Claude, Grok)           OAuth + token refresh)               X-operated)

Two properties to internalize. First, the credentials stay local: your CLIENT_ID and CLIENT_SECRET live on your machine, and only a Bearer token crosses the wire over TLS. Second, guard ~/.xurl — the xurl maintainers warn in plain terms, “Never read or send this file to LLM context,” because it holds live tokens. On a headless box, authenticate first with xurl auth oauth2 --headless before wiring up the bridge.

Install (every client)

Prerequisites for the OAuth path: Node.js (for npx), an X developer app with OAuth 2.0 enabled, and the redirect URI http://localhost:8080/callback registered on that app. Have your CLIENT_ID and CLIENT_SECRET ready.

Step 1 — install and smoke-test xurl

# macOS (Homebrew)
brew install --cask xdevplatform/tap/xurl
# or, cross-platform
npm install -g @xdevplatform/xurl

# smoke-test the bridge against the hosted server
npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

Step 2 — wire it into your client

Cursor / Claude Desktop (/clients/cursor, /clients/claude-desktop) — add to mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": {
        "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
      }
    }
  }
}

Grok Build (~/.grok/config.toml) — note the startup_timeout_sec, which matters on first run:

[mcp_servers.xapi]
command = "npx"
args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]
enabled = true
startup_timeout_sec = 300

[mcp_servers.xapi.env]
CLIENT_ID = "YOUR_X_APP_CLIENT_ID"
CLIENT_SECRET = "YOUR_X_APP_CLIENT_SECRET"

VS Code (GitHub Copilot agent mode, /clients/vscode) — .vscode/mcp.json:

{
  "servers": {
    "xapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": { "CLIENT_ID": "...", "CLIENT_SECRET": "..." }
    }
  }
}

Set startup_timeout_sec to at least 300 in clients that support it, so the first-run browser login has time to complete. On first launch a browser tab opens for OAuth; approve it once and tokens cache to ~/.xurl for subsequent runs.

Self-hosting xMCP instead

If you want the open-source server on your own box:

git clone https://github.com/xdevplatform/xMCP
cd xMCP
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp env.example .env          # add your X API Bearer token
python server.py             # serves http://127.0.0.1:8000/mcp

Community X / Twitter servers in our directory

Before the official launch, the ecosystem filled the gap with community servers — several are catalogued here. They remain useful for free-tier posting experiments and self-hosted setups; just know they are not the first-party option:

X (Twitter)enescinr

1-Click Ready

Interact with X (formerly Twitter) using the Twitter API to post tweets, search content, and explore Twitter API pricing.

communication1.9k1

Browse more under remote MCP servers and the full server directory.

Recipes + prompts

Four workflows where the connector earns its slot, assuming a working OAuth connection:

Recipe 1 — Real-time research over the live feed

Prompt: “Search X for posts from the last 24 hours about the MCP spec update, summarize the main complaints, and list the five accounts driving the conversation.” The agent uses search plus the likers/reposters tools to rank voices. This is the use case that justifies the server.

Recipe 2 — Draft an Article, never auto-publish

The community’s hard-won rule for write access: separate drafting from publishing. As builder @tetsuoai framed it in a popular walkthrough, “the important words are: create a draft, do not publish. Publishing should be a separate explicit command.”

Recipe 3 — Trend triage by location

Prompt: “Get trends for WOEID 23424977 (United States) and flag anything relevant to AI tooling.” The trends-by-WOEID tool is the cleanest way to give an agent geographic awareness of what is spiking right now.

Recipe 4 — Migrate off a scraper

Many builders reached this server from the other side — replacing browser automation or scrapers that fed X data into their agents. One developer’s reaction to the launch was simply that an official, supported path beat the brittle workaround they had been maintaining. If you run a community server or a scraper today, the official MCP is the durable replacement — at the cost of the X API bill.

Pricing + rate limits (read this before connecting an agent)

The MCP layer is free; the X API underneath is not. This is the single most important thing to internalize, and it is exactly the gotcha new users hit:

X moved to a pay-per-use model (announced broadly February 2026, alongside the existing fixed tiers). The MCP routes through whichever plan or credit balance your app uses. The fixed tiers for context:

Writes cost real money on pay-per-use — TechCrunch reports posting is priced around $0.015 per post and $0.20 for a post containing a link, pricing X says is meant to curb spam. And independent analysis warns that pay-as-you-go is not automatically cheaper than a fixed tier at equivalent volume, so model your call pattern before turning an autonomous agent loose.

On rate limits, X’s MCP docs are blunt: “Writes count against rate limits (bookmarks, article_publish) and are stricter than reads; expect occasional 429s and back off.” Build retry-with-backoff into any write-heavy agent, and cap how many calls a single agent run can make. An agent in a loop is a billing and rate-limit event waiting to happen.

What we got wrong (so you don’t)

Three assumptions we carried into setup that the docs quietly corrected:

1. We assumed “hosted” meant pasting the URL into the remote-MCP field. That works only for the read-only app-only Bearer path. For OAuth user context you launch the local xurl mcp bridge — the config uses command: npx, not a bare URL. Once that clicked, every snippet made sense.
2. We assumed “without any setup” meant free. It is free of infrastructure, not free of cost. Every call bills against your X API plan. The @syntr0py reaction above is the universal first-day experience.
3. We assumed first-run would just work after pasting the config. It timed out. The default client startup timeout is too short for the browser OAuth round-trip — set startup_timeout_sec to 300, and make sure the redirect URI on your X app is exactly http://localhost:8080/callback.

Common mistakes

Who this is for (and who it isn’t)

Community signal: useful, with one loud caveat

Reception split cleanly. The convenience won praise — X now joins GitHub, Slack, Notion, Stripe, and Salesforce in shipping an official MCP server, and builders who had been scraping or browser-automating X data welcomed a supported path. The caveat, repeated everywhere, was cost: the pay-per-call reality (the @syntr0py reaction above) was the top first-day surprise.

The credible critical read is about spam and defaults, not capability. TechCrunch’s Sarah Perez noted the obvious tension:

And the longer-standing skeptic’s point is about platform risk. X’s API pricing has whiplashed developers since 2023, and indie builders have learned to treat it warily:

Our read: both critiques are about defaults and durability, not whether the server works. It works. The question is whether you trust X’s pricing and policy to stay stable enough to build on — and whether your wallet survives an agent that calls it in a loop.

The verdict

The bigger picture

The X MCP is one more data point in a clear 2026 pattern: platforms are shipping official MCP servers to become agent-native, turning their REST APIs into endpoints an LLM can drive directly. GitHub, Slack, Notion, Stripe, and Salesforce got there first; X’s differentiator is that its data is the live public conversation, which is hard to source anywhere else.

The interesting tension is governance. A read-only research connector is low-stakes; a connector that can post and publish Articles, billed per call, on a platform whose pricing has changed repeatedly, is a different risk profile. The platforms that win the agent era will be the ones whosedefaults are safe — scoped tokens, clear costs, draft-before-publish — not just the ones whose APIs are reachable. For the broader landscape, see our awesome MCP servers roundup and how MCP compares to other agent standards in Agent Client Protocol vs MCP.

FAQ

Glossary

MCP

Model Context Protocol — the open JSON-RPC standard that lets any LLM client call any tool server.

MCP server

A process that exposes tools (and resources) to an MCP client. Here, X's hosted endpoint.

Streamable HTTP

The MCP transport the hosted X server uses (protocol version 2025-06-18).

stdio

Standard input/output — the local transport the xurl bridge speaks to your client.

xurl

X's official open-source CLI for the X API; xurl mcp bridges a stdio client to the hosted server.

OAuth 2.0 (PKCE)

The auth flow for user context and writes; PKCE secures the browser login without a server secret in transit.

App-only Bearer token

A read-only token with no user context — one Authorization header, no bridge needed.

WOEID

Where-On-Earth ID — a numeric location identifier used by the trends tool.

X Article

X's long-form post format; the MCP can create drafts and publish them.

Full-archive search

Search across X's historical post archive, not just the recent window.

429

HTTP 'Too Many Requests' — the rate-limit response; writes hit it sooner than reads.

Pay-per-use

X's consumption-based API billing: you buy credits and pay per operation.

FastMCP

The Python framework the open-source xMCP server uses to expose the X API spec as tools.

Redirect URI

The OAuth callback URL registered on your X app — must be http://localhost:8080/callback for xurl.

Sources

• Primary — X MCP documentation: docs.x.com/tools/mcp
• Primary — Launch announcement: @XDevelopers, June 30, 2026
• Primary — Open-source server: github.com/xdevplatform/xMCP · CLI bridge: github.com/xdevplatform/xurl
• Web — TechCrunch: X now offers an MCP server · CoinDesk: X rolls out hosted MCP server
• Web — X API pricing context: We Are Founders — X API pricing 2026 · pay-per-use launch: MediaNama
• Community — builder walkthrough: @tetsuoai · pricing reaction: @syntr0py
• Internal — What is MCP · Community X (Twitter) servers · Remote MCP servers