twscrape Twitter/X (read-only)

io.github.jsiletsPublished by GitHub account jsiletsv0.1.2Updated Oct 24, 2026

Read-only X/Twitter MCP: posts, threads, replies, search via twscrape. No API key.

VerifiedSTDIODesktop onlyWeb Search & ScrapingCommunication & Collaboration

Overview

AI-generated overview

Read-only X/Twitter MCP server that lets an assistant fetch posts, threads, replies, quotes, timelines, profiles and search results using your own logged-in…

What you can do
  • Read single posts as clean markdown, including media and external links
  • Read threads, replies and quote-tweets for a given post
  • List a user's recent posts, optionally including replies
  • Search X with operators such as from:, has:media and min_faves:
  • Look up a user profile with bio, location, counts and join date
When to use it
Useful when you want an assistant to research or summarize public X conversations, follow a specific account's recent posts, or pull replies and quotes around a post without paying for the X API or holding a developer account.
Requirements
Runs locally over stdio as a Python package installed with uv tool install or pipx (uvx also listed). Needs a one-time authentication step: launching a dedicated Chrome/Brave profile to sign in to X, attaching to an isolated Chromium profile with a debug port, or supplying auth_token and ct0 cookies via hidden prompts. Optional environment variables cover the data directory, account database, proxy, CDP URL, default result limit and HTTP bearer token.
Before you install
It reuses your own X session, so anyone reaching an exposed HTTP endpoint could act with it; set TWSCRAPE_TWITTER_MCP_AUTH_TOKEN before exposing HTTP. Session cookies are stored on disk and must be shipped to hosted deployments. Reading X this way may violate X's Terms of Service, and accounts can be rate-limited or suspended, so burner accounts are advised. Browser debugging ports expose browser data. Results are incomplete for quotes and vary by session.

Installation

In SourceWeft

  1. Open twscrape Twitter/X (read-only) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

ToolReturns
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

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

Then authenticate once (next section) and verify:

bash
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.

bash
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.

bash
# 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:

bash
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:

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

Client-specific equivalents:

Claude Code
bash
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
toml
[mcp_servers.x]command = "twscrape-twitter-mcp"args = ["serve", "--transport", "stdio"]
Cursor — ~/.cursor/mcp.json
json
{  "mcpServers": {    "x": {      "command": "twscrape-twitter-mcp",      "args": ["serve", "--transport", "stdio"]    }  }}
VS Code — .vscode/mcp.json
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.

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

bash
export TWSCRAPE_TWITTER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
Fly.io
bash
fly launch --no-deployfly volumes create twscrape_twitter_mcp_data --size 1fly 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 varDefaultPurpose
TWSCRAPE_TWITTER_MCP_HOME~/.config/twscrape-twitter-mcpWhere the sqlite account pool lives. Point at a volume in prod.
TWSCRAPE_TWITTER_MCP_DB$TWSCRAPE_TWITTER_MCP_HOME/accounts.dbOverride 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_URLhttp://127.0.0.1:9222Browser DevTools endpoint for login --attach.
TWSCRAPE_TWITTER_MCP_DEFAULT_LIMIT40Default timeline and search result count (1–100).
PORT8080HTTP 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.

Source: README.md at commit dabefb8

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts