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

./x-wing-mcp-hermes.sh

The wrapper uses the repo-local uv environment and launches the server over stdio. stdout is the MCP protocol stream - no other process should write to it.

Analytics integration

x_read_own_analytics is a read-only client of the separate local x-analytics service. It reads the service's stored observations over loopback HTTP and never opens an analytics database or calls X directly.

Collection, OAuth credentials, spend limits, and freshness policy belong to the x-analytics deployment. Keep this MCP tool read-only: agents must not be able to trigger paid analytics collection.

Configure the local endpoint in config/analytics.yaml. x-wing accepts only an http loopback origin, uses a bounded timeout, rejects redirects and oversized/non-JSON responses, and reports a distinct ANALYTICS_SERVICE error when the service is missing or unreachable.

The MCP tool defaults to view="overview". It also supports posts, post_history (requires post_id), followers, and status, with a window_days of 1–30. Responses use x-analytics' versioned envelope with an as_of timestamp and freshness state. Post metrics are cumulative at as_of; reported change always names the two observation timestamps rather than pretending to be a calendar-period total.

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

• uv run python -m pytest tests/ -q passes.

• An MCP handshake via the wrapper script (initialize → tools/list) returns the 22 tools documented above.

• x_data_status reports the configured providers' health without exposing credentials.

• A token check against users/me succeeds, and .env plus auth-state files remain owner-readable only.

Deployment notes

• This repository is relocatable: configure the MCP host with the absolute path to x-wing-mcp-hermes.sh in its checked-out repository.

• Store X credentials only in <repo_root>/.env (mode 0600). Do not duplicate or source them from shared host, agent-profile, or global environment files.

• Register one x-wing MCP server per intended host/profile and apply that host's tool-access policy—for example, exclude write tools from read-only profiles.

• The wrapper reads only the repository-local .env and keeps stdout reserved for the stdio MCP protocol.

Roadmap

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