twscrape-twitter-mcp

PyPI CI Python License: MIT 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

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 mcp add x --scope user -- twscrape-twitter-mcp serve --transport stdio

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

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

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

{
  "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 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"

Clients send Authorization: Bearer <token>.

Configuration

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.