Twitter Scraper Mcp

Twitter/X MCP server for AI agents: search, timelines, threads and profiles via local twscrape sessions, credential-free public tweet lookup, and opt-in posting…

LLM Mart 1 views 153 listing impressions

Connect an MCP agent to X search, recent user posts, conversations and profiles through twscrape. Keep your session on your machine, return structured context with source metadata, and explicitly opt into writes when needed. Session reads and writes do not require a developer API key.

Important

This is an unofficial project, not affiliated with X. Private web endpoints can change or restrict your account. Results are bounded samples; 27 registered tools do not mean every upstream endpoint has been live-verified. Read the disclaimer and current verification notes before use.

What you can do

  • Research with your session. Search with X operators, read recent user posts, inspect threads and collect available metrics/media metadata.
  • Give agents usable context. JSON text and MCP structuredContent, string-safe IDs, source labels, bounded collections and explicit partial/error states.
  • Keep access local. Cookies live in your SQLite account database, outside tool arguments. Browser import is an explicit local command; upstream telemetry is disabled.
  • Control publishing. Plain-text posting/deletion through one named session or optional official API credentials. Writes are off by default and never retried automatically.
  • Look up public links. Default getTweet uses public oEmbed without a session or Python; full long-post text and metrics are not guaranteed.
Path Credentials Scope
Public lookup None One post by ID/URL via oEmbed
Session research Your local X session Search, timelines and additional read tools
Session writes One named session + explicit opt-in Plain-text publish/delete
Official API Developer API credentials Optional read/write provider; access can incur charges

Quickstart

Use Node 22.19+ and Python 3.11+. Node 24 LTS is recommended.

git clone https://github.com/takiAA/twitter-scraper-mcp.git
cd twitter-scraper-mcp
npm ci --ignore-scripts
npm run setup:twscrape
npm run build

Choose a session setup method after signing into x.com in your browser:

# Automatic local import from one Chrome profile
npm run auth:browser -- --browser chrome --profile Default

# Or: manually copy two cookies into hidden terminal prompts
npm run auth:import

See the step-by-step manual tutorial (中文教程) for DevTools locations, what to copy and troubleshooting. Other profiles/browsers, explicit refresh with --replace, OS decryption limits and exported-file import are documented there too.

Verify a read:

npm run test:client -- --search "from:golang"
npm run test:client -- --user golang

For public lookup only, skip Python/session setup and use npm run test:client -- --tweet 20. The repository is currently intended for source installation; package.json remains private to prevent accidental npm publishing.

Connect your agent

Add this stdio server to your MCP client's configuration, replacing the path:

{
  "mcpServers": {
    "twitter": {
      "command": "node",
      "args": ["/absolute/path/twitter-scraper-mcp/dist/index.js"],
      "env": { "TWITTER_ENABLE_WRITE": "false" }
    }
  }
}

Start node directly so npm banners do not enter the protocol stream. No HTTP port or background daemon is needed. .env resolves from the project root; process environment values take precedence. Use Docker if you prefer an isolated runtime.

Example requests for an agent:

From the project's README.

Related servers

Read and write RAGE Package Format archives

23 views

See how ChatGPT, Claude, Gemini and Perplexity read any website. Scored out of 100.

19 views

MCP server for Geargrafx PC Engine / TurboGrafx-16 emulator

19 views

Read-only on-chain intel for AI agents on Base: balances, tokens, gas, tx status. No API keys.

15 views