x-mcp

Give AI agents access to X: read and search posts, publish threads, upload media, manage Lists, send DMs, and see images and video frames.

Install

Requires Node.js 22.18+.

npm install
npm run build

Add it to your MCP client (Claude Desktop, Cursor, Codex, custom agents):

{
  "mcpServers": {
    "x": {
      "command": "node",
      "args": ["/absolute/path/to/x-mcp/dist/index.mjs"],
      "env": { "X_BEARER_TOKEN": "..." }
    }
  }
}

Once published to npm: { "command": "npx", "args": ["-y", "@el4cteo/x-mcp"] }.

Or install the CLI globally:

npm install -g @el4cteo/x-mcp
x-mcp

Related MCP server: x-mcp-server

Sign in

• Public reads — set X_BEARER_TOKEN.

• Posting, DMs, bookmarks — run:

node dist/index.mjs auth --client-id YOUR_OAUTH2_CLIENT_ID

Set the X app callback to http://127.0.0.1:8787/callback. Tokens are stored in ~/.config/x-mcp/credentials.json and refreshed automatically. OAuth 1.0a keys (X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET) also work.

Tools

Ten tools. Each call takes an action plus that action's parameters:

{ "action": "search", "query": "mcp -is:retweet", "max_results": 20 }

Run node dist/index.mjs tools for descriptions.

See images and video

x_media action view returns the post's media as MCP image content.

• Photos come back directly; carousels use media_index (0–3).

• Videos and GIFs are sampled into 1–6 frames when ffmpeg is installed.

• Without ffmpeg you get the preview frame plus the video URL.

Install ffmpeg: winget install Gyan.FFmpeg (Windows), brew install ffmpeg (macOS), sudo apt install ffmpeg (Linux). Or set X_MCP_FFMPEG.

Limit: 15 MB per image, 200 MB per video; raise with X_MCP_MAX_IMAGE_MB / X_MCP_MAX_VIDEO_MB.

Commands

node dist/index.mjs                 # stdio
node dist/index.mjs serve --http    # http://127.0.0.1:3333/mcp
node dist/index.mjs doctor          # credentials + connection check
node dist/index.mjs auth --logout   # remove tokens

Settings

Full list in .env.example.

Safety

• --read-only for research-only agents, --dry-run to preview writes.

• Media downloads reject private addresses; uploads are restricted to media files in allowed roots.

• HTTP mode binds to loopback by default and requires a token off-loopback.

• Posts and DMs are public or permanent — agents are instructed to confirm first.

Development

npm run typecheck
npm test     # 85 tests, no X credentials needed
npm run build

MIT — see LICENSE.