Install XMCP (local) Fresh

XMCP is the official MCP server that exposes X API endpoints as callable tools. It is built on FastMCP, loads the X API OpenAPI spec at startup, and serves an MCP endpoint your AI client connects to.

What you get

200+ tools automatically generated from the OpenAPI spec - search posts, create posts, look up users, manage likes and lists, and more. Streaming and webhook endpoints are excluded (see Limitations).

Prerequisites

• Python 3.9+
• An X Developer Platform app (for tokens) - see Get Developer Access
• Optional: an xAI API key if you want to run the Grok test client

Procedure

flowchart TD
    A[Clone repo] --> B[Create venv + install deps]
    B --> C[Copy env.example to .env]
    C --> D[Add OAuth keys + Bearer token]
    D --> E[Register callback URL in Developer Console]
    E --> F[python server.py]
    F --> G[OAuth consent opens in browser]
    G --> H[Server live at 127.0.0.1:8000/mcp]

Step 1 - Clone and install

Requires Python 3.9+.

git clone https://github.com/xdevplatform/xmcp && cd xmcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Step 2 - Create your local .env

cp env.example .env

Edit .env and set the required values (do not skip):

X_OAUTH_CONSUMER_KEY=your_consumer_key
X_OAUTH_CONSUMER_SECRET=your_consumer_secret
X_BEARER_TOKEN=your_bearer_token   # required even if using OAuth1

The OAuth 1.0a callback defaults are usually fine:

X_OAUTH_CALLBACK_HOST=127.0.0.1
X_OAUTH_CALLBACK_PORT=8976
X_OAUTH_CALLBACK_PATH=/oauth/callback
X_OAUTH_CALLBACK_TIMEOUT=300

See Environment Variables for the complete list, including server host/port and tool filtering.

Step 3 - Register the callback URL

In your X Developer App settings, register the callback URL so the OAuth consent flow can redirect back:

http://<X_OAUTH_CALLBACK_HOST>:<X_OAUTH_CALLBACK_PORT><X_OAUTH_CALLBACK_PATH>

With the defaults that is:

http://127.0.0.1:8976/oauth/callback

Callback mismatch = failed auth

The callback URL in your .env must exactly match the one registered in the Developer Console, including host, port, and path.

Step 4 - Start the server

python server.py

The MCP endpoint is http://127.0.0.1:8000/mcp by default. Host and port are configurable via the MCP_HOST and MCP_PORT environment variables.

Step 5 - Complete OAuth consent

On startup, the server opens a browser for OAuth 1.0a consent and waits for the callback. Tokens are kept in memory only for the lifetime of the server process - they are not persisted across restarts.

For debugging, you can set:

X_OAUTH_PRINT_TOKENS=1        # print tokens
X_OAUTH_PRINT_AUTH_HEADER=1   # print request headers

Step 6 - Connect your AI tool

Point an MCP-compatible client at http://127.0.0.1:8000/mcp. Continue to Connect an MCP Client.

How XMCP builds its tools

sequenceDiagram
    participant S as XMCP server
    participant O as OpenAPI spec
    participant C as MCP client
    S->>O: Fetch spec at startup
    O-->>S: All v2 operations
    S->>S: Exclude stream/webhook ops
    S->>S: Apply X_API_TOOL_ALLOWLIST (if set)
    S->>S: Generate one MCP tool per operation
    C->>S: List tools
    S-->>C: 200+ callable tools

The spec is fetched at startup, so restart the server to pick up any API spec updates.

Verification checklist

• [ ] Repo cloned and dependencies installed
• [ ] .env created with consumer key, secret, and Bearer token
• [ ] Callback URL registered in the Developer Console
• [ ] python server.py starts without error
• [ ] Browser OAuth consent completed
• [ ] http://127.0.0.1:8000/mcp is reachable

Troubleshooting

Symptom	Likely cause	Fix
Server exits immediately	Missing required .env values	Set X_OAUTH_CONSUMER_KEY, X_OAUTH_CONSUMER_SECRET, X_BEARER_TOKEN
OAuth callback never returns	Callback URL not registered or mismatched	Match .env callback to the Developer Console exactly
Browser does not open	Headless environment	Set X_OAUTH_PRINT_* flags and complete consent manually
Tools missing after spec change	Spec cached at startup	Restart server.py

See also

• Configure Credentials
• Connect an MCP Client
• Environment Variables
• Limitations