Xmcp_unofficial

An unofficial MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, ...) read public X (Twitter) data — search, profiles, timelines, replies, followers, trends — without the paid official API.

日本語: README.ja.md

What you need

1. Throwaway X accounts (one or more) Never use your main account; scraping accounts can be locked or suspended at any time. Ready-made accounts can be bought at AccsMarket (https://www.accsmarket.com/en/?ref=818187).

2. A proxy per account (recommended) Running throwaway accounts from your home IP ties them to you. A static residential proxy gives each account its own stable, ordinary-looking IP. We recommend Proxy-Cheap (https://app.proxy-cheap.com/r/wCfesT) — a Static Residential (ISP) IPv4 proxy costs around $3.59/month (as of October 2026; check the site for current pricing).

3. Python 3.10+ and uv

The AccsMarket and Proxy-Cheap links above are affiliate links; using them supports this project at no extra cost to you.

Related MCP server: Twitter/X MCP Server

Tools

All tools are read-only.

user accepts jack, @jack, a numeric id, or https://x.com/jack. tweet accepts an id or a status URL. List tools return {"count", "items", "note"?, "warnings"?} — note explains partial or empty results.

Install

Requires Python 3.10+ and uv.

uv tool install git+https://github.com/Kevin-OS7/Xmcp_unofficial

or from a clone: uv sync && uv run xmcp-unofficial --help.

Setup

Run the interactive setup once. It registers throwaway accounts (cookies are entered hidden), checks each proxy can reach x.com, sets the request delay, and verifies the result with a real request:

xmcp-unofficial setup

To get cookies: log in to x.com with a dedicated account, open DevTools → Application → Cookies → https://x.com, and copy auth_token and ct0 (auth_token=...; ct0=..., or a JSON cookie export).

Already have accounts in a twscrape database? Import them:

xmcp-unofficial accounts import /path/to/twscrape/accounts.db

Non-interactive account commands:

xmcp-unofficial accounts add my_reader --cookies "auth_token=xxxx; ct0=yyyy" --proxy http://user:pass@host:port
xmcp-unofficial accounts set-proxy my_reader http://user:pass@host:port   # or "none"
xmcp-unofficial accounts list      # status of all accounts
xmcp-unofficial accounts check     # fetch a profile to confirm it works
xmcp-unofficial accounts remove my_reader

Multiple accounts are rotated automatically; a rate-limited account is skipped until its limit resets. Accounts are stored in ~/.xmcp_unofficial/accounts.db.

Connect to an MCP client

Claude Code

claude mcp add x-scraper -- xmcp-unofficial

Claude Desktop / Cursor / others (mcpServers JSON):

{
  "mcpServers": {
    "x-scraper": {
      "command": "xmcp-unofficial"
    }
  }
}

Without installing: "command": "uvx", "args": ["--from", "git+https://github.com/Kevin-OS7/Xmcp_unofficial", "xmcp-unofficial"].

Configuration

Settings are read from ~/.xmcp_unofficial/config.toml (written by setup), so every MCP client shares them. An XMCP_* environment variable, e.g. in a client's env block, overrides the file.

req_delay = "1.5"      # seconds between paginated requests: 1.5 fixed, "1-3" random, 0 none
timeout = 120
max_limit = 200
# proxy = "http://user:pass@host:port"   # applies to every account
# db = "~/.xmcp_unofficial/accounts.db"

Troubleshooting

• Empty results with warnings mentioning ConnectError — the account's proxy is unreachable. Fix it with xmcp-unofficial accounts set-proxy <user> <url> (or none to connect directly).

• "No active scraping accounts" — add one, or check accounts list: accounts whose cookies expired or that got banned are marked inactive. Re-add them with fresh cookies.

• Timeouts / partial results — all accounts are rate-limited for that endpoint. Add accounts or wait ~15 minutes. accounts reset-locks clears stale locks.

Development

uv sync --extra dev
uv run pytest
uv run ruff check src tests

The scraping engine is a vendored copy of twscrape in src/xmcp_unofficial/_vendor/twscrape/. When X changes its GraphQL operation IDs, update the OP_* constants in api.py there.

License & credits

MIT. The scraping engine is derived from twscrape by vladkens (MIT License); see NOTICE for the full attribution and list of modifications.