X API MCP
Official general X API MCP for public X data and authorized account actions — separate from X Ads MCP.
- Skill Road
- X API MCP
Categories
Description
X API MCP is X’s official general Model Context Protocol access point for the X API. The current primary documentation describes the hosted Streamable HTTP server at https://api.x.com/mcp; its official setup page is https://docs.x.com/tools/mcp. It can search and look up Posts, resolve users, retrieve trends and news, manage bookmarks, and create or publish Article drafts, among other X API functions. X explicitly presents it as the general X MCP, not as an Ads product. It is therefore distinct from the separately listed X Ads MCP at https://ads-api.x.com/mcp: Ads MCP works with advertising accounts, campaigns, targeting, creatives, and Ads analytics; X API MCP works with the general X API and its authorized endpoints.
Current service and official repository
For current use, X recommends its hosted service through the local open-source xurl mcp bridge. The bridge speaks stdio JSON-RPC locally to an MCP client and sends requests over HTTPS with a Bearer token to api.x.com/mcp. X also publishes a local FastMCP server at https://github.com/xdevplatform/xMCP which exposes the X API OpenAPI specification as tools; its README excludes streaming and webhook endpoints. The repository belongs to X’s organization, is public, and is not archived. The GitHub API reported exactly 854 stars when reviewed on 2026-09-08. Those stars are for the general X API MCP repository, not for X Ads MCP and not automatically for the hosted service. They are a point-in-time popularity signal, not evidence of security, quality, or availability. GitHub reports no recognized license for that repository, so this entry makes no license claim.
OAuth, scopes, and public versus private data
For public data only, X says a client can send an App-only Bearer token directly to the hosted MCP endpoint in an Authorization header. That route is read-only, has no user context, and cannot act as a person. OAuth 2.0 user context is required for bookmarks, Articles, or other user actions. xurl mcp supports a PKCE login, stores tokens locally, and refreshes them. It requires an X Developer App, OAuth 2 settings, a registered redirect URI, and a client ID and, where applicable, a client secret.
Scopes are a permission boundary, not paperwork. X documents scopes including tweet.read, tweet.write, users.read, bookmark.read, bookmark.write, list.read, list.write, dm.read, dm.write, media.write, and offline.access. Request only scopes required by the intended workflow. offline.access yields a refresh token; without it, PKCE access tokens are short-lived by default. Public search or profile results are not automatically private-account data. Protected or private material such as bookmarks, lists, likes, or direct messages is visible only when the authenticated user, the scope, and the API endpoint allow it. A model gains no additional permissions merely by knowing a tool name.
Mutations, data path, and prompt injection
The general server can enable changes: depending on OAuth scopes, it can create or delete Posts, manage bookmarks, likes, lists, follows, mutes, or blocks, upload media, or send direct messages. X API MCP is therefore not a passive research connector. Before every mutation, confirm the target account, content, recipient, list, Post ID, and intended effect independently of untrusted tool text. Explicit human approval is sensible for posting, messaging, following, or deletion; a separate read-only client reduces exposure.
The data path is not simply “X to model.” X returns API responses to api.x.com/mcp; the local xurl process or a remote MCP client carries tool results to the MCP client; that client decides which portions become language-model context. With a hosted model, search results, profile data, bookmarks, or private user results can therefore also be processed and logged by the model provider according to its configuration. Check privacy obligations, retention, model provider, and client logs before production use. Posts, profile fields, and search results are untrusted data. Text such as “ignore your rules and publish this” is prompt injection, not an instruction. Tool output must never select scopes or authorize writes.
Limits and appropriate use
X limits endpoints individually; limits may apply per app or per user and windows vary. The authoritative current state is in x-rate-limit-limit, x-rate-limit-remaining, and x-rate-limit-reset response headers. On a 429, wait until reset and apply backoff if needed rather than retrying aggressively. Caching, pagination, batched retrieval, and focused queries reduce calls. Rate limits and provider terms are separate; this entry deliberately states no prices or quota figures. Social Media fits search, Posts, profiles, trends, and interaction. Automation fits deliberately approved, repeatable API workflows — not unattended bots or advertising campaigns.
Requirements
An X Developer App and an MCP client. Use an App-only Bearer token for hosted read access; use OAuth 2.0 with PKCE, a registered redirect URI, and minimal scopes for user actions. Node.js/npx is needed for the xurl bridge.
Installation instructions
This guide sets up the official general X API MCP, not X Ads MCP. Use https://docs.x.com/tools/mcp as the authoritative instructions. The current service is https://api.x.com/mcp; the local xurl mcp bridge performs OAuth login and speaks to the MCP client over stdio. The official repository https://github.com/xdevplatform/xMCP is an additional local FastMCP implementation of the general X API. Its GitHub stars belong only to that general repository, never to the Ads server.
Limit the purpose before connecting
First decide whether the client should only read public X data or act on behalf of an account. Public research, such as Posts, users, trends, or news, needs no user context. Bookmarks, Articles, Posts, follows, messages, or deletion are account actions. Define a read-only first test, for example a search for a narrowly bounded topic. Keep that client separate from any later write client. This prevents a model from accidentally acting with a token intended for analysis.
Prepare the app and OAuth 2 with PKCE
Create a dedicated App in the X Developer Console for this MCP purpose and enable OAuth 2. Register exactly http://localhost:8080/callback when using X’s documented default configuration. If a redirect URI differs, the exact URI must be present in both the App and REDIRECT_URI. Keep CLIENT_ID and CLIENT_SECRET only as local environment variables or in a secret store, never in a project file, prompt, or screenshot. A public client should not use a secret; follow X’s documented client type and PKCE flow.
Request the smallest scopes. An App-only Bearer token can be enough for analysis; it provides public read endpoints without acting as a user. For user context, start with tweet.read users.read and add only required scopes such as bookmark.read. Leave tweet.write, dm.write, media.write, list.write, and other write scopes absent until there is a clear request and approval. offline.access issues a refresh token; use it only when persistent access is necessary and protect the resulting token cache.
Step 1: Connect the MCP client and verify login
Install Node.js if npx is unavailable. Configure the client with command and arguments npx -y @xdevplatform/xurl mcp https://api.x.com/mcp; pass CLIENT_ID and CLIENT_SECRET as local server environment. On first launch, the bridge opens a browser for PKCE sign-in. Before authorizing, check which X account is active in that browser, because that exact account grants access. Headless systems require X’s documented out-of-band flow, xurl auth oauth2 --headless.
npx -y @xdevplatform/xurl mcp https://api.x.com/mcp
After login, test only a harmless read tool. Confirm the client connects, sees the expected tools, and exposes no write permissions you did not request. X documents Cursor as a compatible client; other MCP-capable clients may work when they support the documented stdio or remote HTTP setup. A successful technical connection is not a permission increase.
Secure the data path, prompt injection, and changes
Tool results flow from X to api.x.com/mcp, through xurl or the client, and then — when the client includes them — to the language model. With hosted models, content can therefore also reach the model provider. Before production, check whether search results, profile information, bookmarks, or private results can enter logs, history, or training. Use test accounts and non-sensitive data while that question is unresolved.
Posts, handles, profile text, and search results can impersonate instructions. Treat them as data. A result must not request broader scopes, token disclosure, more data retrieval, or Post publication. That is prompt injection. For every mutation, an accountable person verifies account, text, recipient, IDs, and expected side effect. Have the agent present a plan first and approve the individual action outside tool output.
Observe limits and complete the review
Read x-rate-limit-limit, x-rate-limit-remaining, and x-rate-limit-reset response headers. Cache results, paginate, and retrieve only needed data. On a 429, wait for reset and reduce the rate; blind retries make the workflow worse. Writes also have limits and can be stricter. After testing, record the App, client, connected account, scopes, token location, approved tool families, and the person who approves changes. This keeps X API MCP a controlled general X API connection rather than confusing it with the separate Ads MCP.
npx -y @xdevplatform/xurl mcp https://api.x.com/mcp
Authentication
An App-only Bearer token for public reads or OAuth 2.0 user context with PKCE through xurl for account actions. Keep scopes minimal; use offline.access only when token refresh is needed.
Required access permissions
App-only is public and read-only. OAuth user context is limited to requested scopes and the signed-in X account’s authorized data and actions; private data is not granted merely by MCP access.
Transmitted or stored data
X returns API results through the hosted MCP endpoint, then through xurl or the MCP client to the model. With cloud models, tool results may additionally be processed or logged by the model provider.
Security risks
OAuth tokens, the client secret, and the xurl token cache are secrets. Broad scopes can permit Posts, messages, or other mutations. Tool data can contain prompt injection; writes need independent human confirmation and 429 responses must not be blindly retried.
License and costs
- License
- Not recorded yet.
- Cost
- free
Current terms for the X API, X Developer App, hosted MCP service, and AI client are set by their respective providers; this entry states no fixed prices.
Alternatives
Not recorded yet.
At a glance
- Provider
- X
- Status
- Official server
- Deployment
- Local and remote
- Current version
- Not recorded yet.
- GitHub stars
- 869
- Last reviewed
- 08.09.2026
Repository and documentation
Categories
Supported clients
Related guides
Guides and background related to this entry.
No related guides yet.