X MCP

About

X MCP is X's official hosted MCP server for the X API. X documents the endpoint as https://api.x.com/mcp with serverInfo: xmcp; most local MCP clients connect through the open-source xurl mcp bridge, which handles OAuth and forwards stdio JSON-RPC traffic to the hosted Streamable HTTP endpoint.

This entry focuses on the X API MCP server, not the separate official Docs MCP endpoint at https://docs.x.com/mcp and not similarly named community Twitter/X MCP repositories.

Key Features

• Calls X API capabilities from MCP-compatible tools using the user's X account permissions.
• Documented capability categories include posts, full-archive post search, user search, user lookup, timelines, mentions, bookmarks, bookmark folders, news, trends, and Articles.
• Uses xurl for OAuth 2.0 user-context authentication, token caching, and token refresh.
• Supports a documented app-only direct URL mode for read endpoints in clients that can attach a static Bearer token.

Use Cases

• Social listening and research workflows that need live X search or user context.
• Agent-assisted account workflows such as bookmark management, timeline lookup, mentions review, and Article drafting.
• X API prototyping from AI tools while keeping the MCP client connected to the same API surface documented by X.

Compatibility

X documents setup paths for Grok Build, Cursor, Claude Desktop, VS Code with GitHub Copilot Agent mode, and generic MCP-compatible clients. The checked official page does not provide separate public setup instructions for Claude Code, Codex, Windsurf, or Lovable.

Limitations

The hosted X API MCP server requires an X Developer Platform app for OAuth. X also notes that the remote MCP endpoint does not advertise native MCP OAuth discovery or dynamic client registration, so the local xurl bridge is the recommended path for full user-context functionality. Direct app-only HTTP usage is read-focused, lacks auto-refresh, and does not act as the user.

The official page lists capability categories rather than a complete fixed public inventory of every exposed tool name for the hosted X API MCP server.

Sources

• Official X MCP documentation: https://docs.x.com/tools/mcp
• xurl GitHub repository: https://github.com/xdevplatform/xurl
• X API OpenAPI specification: https://api.x.com/2/openapi.json
• Local FastMCP comparison repository: https://github.com/xdevplatform/xmcp

MCP Setup

Prerequisites

• Node.js installed for the documented npx-based bridge setup
• X Developer Platform account
• X Developer Platform app with OAuth 2.0 enabled
• Redirect URI registered on the X app, defaulting to http://localhost:8080/callback unless REDIRECT_URI is changed
• CLIENT_ID and CLIENT_SECRET from the X app

Access requirements

• First-run OAuth 2.0 browser sign-in is required for user-context access
• The xurl bridge caches tokens under ~/.xurl and refreshes them after authentication
• Endpoint access, writes, and rate limits depend on the X API app package, environment, scopes, and account permissions
• App-only direct URL mode is documented for read endpoints only and uses a static Bearer token instead of user context

Companion app or plugin

Name: xurl CLI / @xdevplatform/xurl Install URL: https://github.com/xdevplatform/xurl

• Use the documented npx launcher in MCP client configuration; no separate install is required for that path.
• Optional native installs documented by X include Homebrew, npm global install, shell script, and Go install.
• Use xurl mcp to bridge local stdio MCP clients to the hosted https://api.x.com/mcp endpoint.

xurl handles OAuth, token caching, token refresh, and bearer-token injection for the hosted X MCP endpoint.

Client setup

Grok Build

Transport: stdio

grok mcp add xapi npx -e CLIENT_ID=YOUR_X_APP_CLIENT_ID -e CLIENT_SECRET=YOUR_X_APP_CLIENT_SECRET -- -y @xdevplatform/xurl mcp https://api.x.com/mcp

[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"

• Run the documented grok mcp add command, or edit ~/.grok/config.toml with the xapi server block.
• Run grok mcp doctor xapi and grok mcp list to verify the server.

Auth:

• The first doctor or tool invocation opens the browser for X OAuth login.
• Complete the one-time login so xurl can cache and refresh the token.

Documented by X for Grok Build; args after -- are passed to npx.

Claude Code

Exact public Claude Code setup is not documented on the checked official X MCP page.

Claude Desktop

Transport: stdio

npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

{
  "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"
      }
    }
  }
}

• Edit claude_desktop_config.json in the Claude Desktop config directory.
• Add the xapi mcpServers block.
• Restart Claude Desktop and check that the X tools appear in the tools menu.

Auth:

• On first use, the xurl bridge opens a browser for X OAuth login.
• Complete the login once so xurl can cache and refresh the token.

The hosted MCP endpoint is Streamable HTTP, but Claude Desktop connects through the local stdio xurl bridge.

Cursor

Transport: stdio

npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

{
  "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"
      }
    }
  }
}

• Create ~/.cursor/mcp.json for global use or .cursor/mcp.json for a project.
• Open Cursor Settings, then MCP, and confirm xapi shows as connected after the handshake.

Auth:

• On first use Cursor spawns the bridge and the browser opens for X OAuth login.
• Complete the login; the tool list populates after the handshake completes.

Use a generous startup timeout if the client supports it because first-run OAuth holds the MCP handshake.

Codex

Exact public Codex setup is not documented on the checked official X MCP page.

Windsurf

Exact public Windsurf setup is not documented on the checked official X MCP page.

VS Code

Transport: stdio

npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

{
  "servers": {
    "xapi": {
      "type": "stdio",
      "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"
      }
    }
  }
}

• Add the server definition to .vscode/mcp.json for GitHub Copilot Agent mode.

Auth:

• The first run uses the xurl OAuth browser login flow unless a cached token already exists.

Documented by X for VS Code with GitHub Copilot Agent mode.

Lovable

Exact public Lovable setup is not documented on the checked official X MCP page.

Other

Transport: stdio

npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

{
  "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"
      },
      "startup_timeout_sec": 300
    }
  }
}

• Use the universal stdio MCP configuration in any compatible client.
• If the client supports startup timeouts, set at least 300 seconds for the first OAuth login.
• For Grok Build, X documents adding the server with the grok mcp add command and the same npx bridge arguments.

Auth:

• Run the client and complete the first-run browser OAuth flow.
• For headless or remote machines, authenticate out of band first with xurl auth oauth2 --headless.

If xurl is installed natively, X documents replacing command npx and args with command xurl and args ["mcp", "https://api.x.com/mcp"].

Other

Transport: HTTP

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

• Use only with MCP clients that support remote MCP endpoints with custom headers.
• Provide an app-only Bearer token in the Authorization header.

Auth:

• Create or retrieve an app-only Bearer token from the X Developer Platform.
• Do not use this mode when user-context actions or token auto-refresh are required.

X documents this as a read-endpoint trade-off: no auto-refresh and no user context. The xurl bridge is recommended for full functionality.

Authorization flow

• Create an X app in the X Developer Portal with OAuth 2.0 enabled.
• Register http://localhost:8080/callback as the redirect URI, or set REDIRECT_URI and register that URI instead.
• Put CLIENT_ID and CLIENT_SECRET in the MCP client environment or register them in xurl.
• Start the MCP client; xurl opens a browser for the one-time OAuth 2.0 login and caches the token.
• For a headless host, run xurl auth oauth2 --headless before starting the MCP bridge.
• For read-only direct HTTP usage, provide an app-only Bearer token as an Authorization header instead of using the bridge.

Environment variables

• CLIENT_ID
• CLIENT_SECRET
• REDIRECT_URI optional
• AUTH_URL optional advanced override
• TOKEN_URL optional advanced override
• API_BASE_URL optional advanced override
• INFO_URL optional advanced override

Setup docs: https://docs.x.com/tools/mcp