119 lines
3.4 KiB
Markdown
119 lines
3.4 KiB
Markdown
# X API FastMCP Server
|
|
|
|
Run a local MCP server that exposes the X API OpenAPI spec as tools using
|
|
FastMCP. Streaming and webhook endpoints are excluded.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.9+
|
|
- An X Developer Platform app (to get tokens)
|
|
- Optional: an xAI API key if you want to run the Grok test client
|
|
|
|
## Quick start (local server)
|
|
|
|
1. Create a virtual environment and install dependencies:
|
|
- `python -m venv .venv`
|
|
- `source .venv/bin/activate`
|
|
- `pip install -r requirements.txt`
|
|
2. Create your local `.env`:
|
|
- `cp env.example .env`
|
|
- Fill in the OAuth1 section (consumer key/secret and callback settings).
|
|
3. Run the server:
|
|
- `python server.py`
|
|
|
|
The server starts at `http://127.0.0.1:8000` by default.
|
|
The MCP endpoint is `http://127.0.0.1:8000/mcp`.
|
|
|
|
## Environment variables
|
|
|
|
Required (OAuth1 user context):
|
|
- `TWITTER_CONSUMER_KEY`
|
|
- `TWITTER_CONSUMER_SECRET`
|
|
- `X_OAUTH_CALLBACK_HOST` (default `127.0.0.1`)
|
|
- `X_OAUTH_CALLBACK_PORT` (default `8976`)
|
|
- `X_OAUTH_CALLBACK_PATH` (default `/oauth/callback`)
|
|
- `X_OAUTH_CALLBACK_TIMEOUT` (default `300`)
|
|
|
|
Optional auth fallback:
|
|
- `X_BEARER_TOKEN` (OAuth2 bearer token)
|
|
|
|
Optional server config:
|
|
- `MCP_HOST` (default `127.0.0.1`)
|
|
- `MCP_PORT` (default `8000`)
|
|
- `X_API_BASE_URL` (default `https://api.x.com`)
|
|
- `X_API_TIMEOUT` (default `30`)
|
|
- `X_API_DEBUG` (default `1`)
|
|
- `FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER`
|
|
|
|
Tool filtering (comma-separated):
|
|
- `X_API_TOOL_TAGS`
|
|
- `X_API_TOOL_ALLOWLIST`
|
|
- `X_API_TOOL_DENYLIST`
|
|
|
|
Optional Grok test client:
|
|
- `XAI_API_KEY`
|
|
- `XAI_MODEL` (default `grok-4-1-fast`)
|
|
- `MCP_SERVER_URL` (default `http://127.0.0.1:8000/mcp`)
|
|
|
|
## Auth flow (OAuth1 on startup)
|
|
|
|
The server runs an OAuth1 browser flow on startup and uses the resulting
|
|
access token to sign every request. You must register a callback URL in your
|
|
X Developer App that matches:
|
|
|
|
```
|
|
http://<X_OAUTH_CALLBACK_HOST>:<X_OAUTH_CALLBACK_PORT><X_OAUTH_CALLBACK_PATH>
|
|
```
|
|
|
|
Example:
|
|
|
|
```
|
|
http://127.0.0.1:8976/oauth/callback
|
|
```
|
|
|
|
When you start the server, it will open a browser tab for consent and wait
|
|
for the callback. Tokens are kept in memory only for the lifetime of the
|
|
server process.
|
|
|
|
## Tool whitelisting
|
|
|
|
If you want to limit the tool list (smaller context window, fewer tools),
|
|
use `X_API_TOOL_ALLOWLIST` or `X_API_TOOL_TAGS` in `.env`.
|
|
|
|
Example allowlist:
|
|
|
|
```
|
|
X_API_TOOL_ALLOWLIST=getUsersByUsername,createDirectMessagesByParticipantId
|
|
```
|
|
|
|
Example tags:
|
|
|
|
```
|
|
X_API_TOOL_TAGS=users,dm
|
|
```
|
|
|
|
Allowlist and tags are applied at startup when the OpenAPI spec is loaded.
|
|
|
|
## Generate an OAuth2 user token (optional)
|
|
|
|
If you want a user-context OAuth2 token:
|
|
1. Add `CLIENT_ID` and `CLIENT_SECRET` to your `.env`.
|
|
2. Update `redirect_uri` in `generate_authtoken.py` to match your app settings.
|
|
3. Run `python generate_authtoken.py` and follow the prompts.
|
|
4. Copy the printed access token into `.env` as `X_OAUTH_ACCESS_TOKEN`.
|
|
|
|
## Run the Grok MCP test client (optional)
|
|
|
|
1. Set `XAI_API_KEY` in `.env`.
|
|
2. Make sure your MCP server is running locally (or set `MCP_SERVER_URL`).
|
|
3. If Grok cannot reach `http://127.0.0.1:8000/mcp`, use ngrok to tunnel your
|
|
local server and point `MCP_SERVER_URL` to the public ngrok URL.
|
|
4. Run `python test_grok_mcp.py`.
|
|
|
|
## Notes
|
|
|
|
- Endpoints with `/stream` or `/webhooks` in the path are excluded.
|
|
- Operations tagged `Stream` or `Webhooks`, or marked with
|
|
`x-twitter-streaming: true`, are excluded.
|
|
- The OpenAPI spec is fetched from `https://api.twitter.com/2/openapi.json` at
|
|
startup.
|