twscrape-twitter-mcp

An MCP server that reads X (Twitter): posts, threads, replies, quotes, and search. It wraps twscrape and uses your own logged-in session, so there's no paid X API and no developer account. Tools return clean markdown shaped for an agent to read, including image, video, and GIF URLs and any external links in a post.

Works with any MCP client over the two standard transports — local stdio and hosted Streamable HTTP.

Tools

Tool	Returns
read_tweet(url_or_id)	One post as markdown.
read_thread(url_or_id, max_replies=50)	Root post + the author's self-thread + top replies.
read_replies(url_or_id, limit=50)	Replies to a post.
read_quotes(url_or_id, limit=30)	Quote-tweets (best-effort, search-based).
user_timeline(username, limit=40, include_replies=False)	A user's recent posts, newest first. Set include_replies=True to include replies.
search(query, limit=20, product="Latest")	Search results. Supports from:, has:media, min_faves:, etc.
user_profile(username)	A user's profile as markdown: bio, location, follower/following/tweet counts, join date.

Install

uv tool install twscrape-twitter-mcp     # or: pipx install twscrape-twitter-mcp

Then authenticate once (next section) and verify:

twscrape-twitter-mcp smoke               # reads one public tweet end-to-end

Authenticate

Reads run against your own X session. Pick one path:

1. Launch a dedicated browser (recommended). Opens a separate Chrome/Brave profile with a DevTools port, you sign in to X once, and the session is captured. It does not touch your daily browser or automate X's login flow.

twscrape-twitter-mcp login --launch-browser chrome   # or: brave

2. Attach to a dedicated browser profile. Only use this when you already run an isolated Chromium profile with a debug port. Browser debugging exposes browser data, and recent Chrome versions do not enable it for the default profile.

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/x-mcp-browser
# Linux:   google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/x-mcp-browser
# Windows: "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=%TEMP%\x-mcp-browser

twscrape-twitter-mcp login --attach                  # add --cdp-url for a non-default port

3. Headless / CI (raw cookies). A server can't open your desktop browser, so add a session from auth_token + ct0 cookies. Run this without cookie flags to enter values through hidden prompts, rather than leaving secrets in shell history:

twscrape-twitter-mcp init

The captured session is reused across restarts. Run login --launch-browser chrome again when it expires, or to add burner sessions for rate-limit rotation. twscrape-twitter-mcp accounts lists the pool.

Use burner accounts, not your main — see Legal.

Connect your client

The server runs locally over stdio. Most MCP clients take a JSON block like this:

{
  "mcpServers": {
    "x": {
      "command": "twscrape-twitter-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Client-specific equivalents:

Claude Code

claude mcp add x --scope user -- twscrape-twitter-mcp serve --transport stdio

Claude Desktop

Add the JSON block above to claude_desktop_config.json (Settings → Developer → Edit Config).

Codex — ~/.codex/config.toml

[mcp_servers.x]
command = "twscrape-twitter-mcp"
args = ["serve", "--transport", "stdio"]

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "x": {
      "command": "twscrape-twitter-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "x": {
      "command": "twscrape-twitter-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Remote (Streamable HTTP)

For a hosted private instance (see Deploy), point a preconfigured client at the HTTP endpoint with a bearer token. This is static bearer auth, not an OAuth sign-in flow.

{
  "mcpServers": {
    "x": {
      "url": "https://YOUR-APP.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Then ask, e.g. "read this thread: <url>".

Deploy

Run the server always-on and reachable over HTTP (POST /mcp). It ships as a container; Cloudflare Workers won't work because twscrape is Python with native deps.

A headless container can't open your desktop browser, so authenticate locally first (login --attach writes storage_state.json under TWSCRAPE_TWITTER_MCP_HOME), then ship that session to the host — copy the file to the mounted volume, or run the cookie-based init over SSH. The server reloads a persisted session on boot.

Always set a token when exposing HTTP — anyone who can reach the endpoint can use your X session:

export TWSCRAPE_TWITTER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)

Fly.io

fly launch --no-deploy
fly volumes create twscrape_twitter_mcp_data --size 1
fly secrets set TWSCRAPE_TWITTER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
fly deploy
# seed a session onto the volume through hidden prompts:
fly ssh console -C "twscrape-twitter-mcp init"

Railway

Point Railway at this repo (it reads railway.json + Dockerfile), add a volume mounted at /data, set TWSCRAPE_TWITTER_MCP_AUTH_TOKEN, and seed a session via the Railway shell with twscrape-twitter-mcp init.

Clients send Authorization: Bearer <token>.

Configuration

Env var	Default	Purpose
TWSCRAPE_TWITTER_MCP_HOME	~/.config/twscrape-twitter-mcp	Where the sqlite account pool lives. Point at a volume in prod.
TWSCRAPE_TWITTER_MCP_DB	$TWSCRAPE_TWITTER_MCP_HOME/accounts.db	Override the pool path directly.
TWSCRAPE_TWITTER_MCP_AUTH_TOKEN	(unset)	Required bearer token for HTTP transport.
TWSCRAPE_TWITTER_MCP_PROXY	(unset)	Global proxy for every account.
TWSCRAPE_TWITTER_MCP_CDP_URL	http://127.0.0.1:9222	Browser DevTools endpoint for login --attach.
TWSCRAPE_TWITTER_MCP_DEFAULT_LIMIT	40	Default timeline and search result count (1–100).
PORT	8080	HTTP port (Railway injects this).

How it works

The hard part of reading X — GraphQL signing, the x-client-transaction-id header, TLS fingerprinting — lives entirely in twscrape, which is pinned. This package is a read-only MCP layer on top and never touches that machinery. When X changes something and reads break, the fix is a version bump, not reverse-engineering.

Limits

• X can expire, rate-limit, or suspend the account behind your session.
• Protected, deleted, geo-blocked, or otherwise restricted posts may not be readable.
• Quote-tweet coverage is search-based and incomplete.
• Search results depend on X's current search behavior and can vary by session.
• It does not decrypt browser cookie stores — use browser attach or cookie init.

Legal

Reading X with your own logged-in session may violate X's Terms of Service, and accounts used for scraping can be rate-limited or suspended. Use burner accounts, not your main. Provided as-is for research and personal use; you are responsible for how you use it.

License

MIT.

Credits

The hard scraping work is twscrape by vladkens. This is a read-only MCP layer on top — go star it.