x-wing-mcp

A stdio MCP server for X (Twitter) that combines x-wing write tools with x_data read tools. All tools share one process, one .env, and one official xdk OAuth 2.0 app.

Tools

Write tools

Read tools

Read tools use an internal provider router (official_x, syndication, socialdata, getxapi). max_cost_usd is required on every read tool except status/healthcheck.

Related MCP server: X(Twitter) V2 MCP Server

Provisioning

1. Ensure this repo's .env exists and is readable only by the owner:

   chmod 600 .env

2. Populate .env with OAuth 2.0 credentials from the X developer portal:

   X_OAUTH2_CLIENT_ID=...
   X_OAUTH2_CLIENT_SECRET=...
   X_OAUTH2_ACCESS_TOKEN=...
   X_OAUTH2_REFRESH_TOKEN=...
   X_OAUTH2_SCOPES="offline.access dm.read tweet.write like.write like.read users.read dm.write tweet.read bookmark.write follows.write follows.read"

   Legacy aliases (X_CLIENT_ID, X_CLIENT_SECRET, X_ACCESS_TOKEN, X_REFRESH_TOKEN, X_SCOPES) are also accepted.

3. Optional paid/backup providers:

   SOCIALDATA_API_KEY=...
   GETXAPI_API_KEY=...

   Leave blank to rely on official_x + syndication only.

4. If the access token is expired, run the included OAuth setup script or use the CLI refresh path to obtain a fresh token.

Running

python -m server

The server speaks MCP over stdio. stdout is the MCP protocol stream — no other process should write to it.

Testing

python -m pytest tests/ -q

Project layout

.
├── .env                 # real tokens, gitignored, chmod 600
├── .env.example         # committed template
├── .gitignore           # ignores .env and auth-state files
├── pyproject.toml       # x-wing-mcp package metadata
├── README.md            # this file
├── x_client.py          # vendored + patched x-wing client
├── oauth_setup.py       # vendored + patched OAuth setup
├── server.py            # FastMCP stdio server (read + write tools)
├── xdata/               # vendored x_data read providers/router/server
├── config/              # provider routing configuration
└── tests/               # vendored + new MCP tests

Verification results

• python -c "import x_client; print(x_client.env_path)" → <repo_root>/.env

• MCP handshake via the wrapper script: initialize → tools/list returns exactly the 20 tools above.

• x_data_status reports all configured providers healthy when tokens/keys are present.

• Live token check via _validate_access_token against users/me: valid after refresh (access token refreshed successfully; .env and auth-state remain 0600).

Deployment notes

• This repo is repo-relative; it can be relocated without changes.

• Tokens live only in <repo_root>/.env. After migration, no X OAuth tokens should remain in ~/.hermes/.env or profile .env files.

• The merged x-wing Hermes MCP server is wired into:

  • ~/.hermes/config.yaml (default / main profile)

  • ~/.hermes/profiles/yan-cgo/config.yaml

  • ~/.hermes/profiles/scout/config.yaml — read-only via tools.exclude on the 7 write tools

• Wrapper script: x-wing-mcp-hermes.sh (repo root, executable). It deliberately does not source ~/.hermes/.env; the server reads tokens exclusively from <repo_root>/.env.

Roadmap

See AGENTS.md. Repo reconciliation is already complete: this repo (bob0x-ai/x-wing-mcp) is the canonical source of truth.