# X MCP

X MCP is the official hosted Model Context Protocol server for calling X API endpoints from MCP-compatible tools. It connects through the xurl bridge so agents can search posts, look up users, manage bookmarks, fetch trends and news, and work with Articles using the user's X account permissions.

Canonical URL: https://a2a-mcp.org/entry/x-mcp

Language: en

Category: MCP Servers

Updated: 2026-06-30

## 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`

```bash
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
```

```json
[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`

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

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

- 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`

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

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

- 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`

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

```json
{
  "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`

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

```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"
      },
      "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`

```json
{
  "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

## Tags

- MCP
- X API
- Twitter
- social media
- OAuth
- stdio
- hosted

## Also known as

- X MCP
- X API MCP
- X MCP server
- Twitter MCP
- Twitter MCP server
- api.x.com/mcp
- xurl mcp

## Alternatives

- X Docs MCP
- xdevplatform/xmcp
- X Twitter MCP Server
- DataWhisker X MCP Server
- TwitterAPI.io MCP

## Sources

- [Project website](https://docs.x.com/tools/mcp)
- [Official X MCP documentation](https://docs.x.com/tools/mcp)
- [Hosted X MCP endpoint](https://api.x.com/mcp)
- [xurl GitHub repository](https://github.com/xdevplatform/xurl)
- [xdevplatform/xmcp GitHub repository](https://github.com/xdevplatform/xmcp)
- [X API OpenAPI specification](https://api.x.com/2/openapi.json)

Last checked: 2026-06-30