convez.ai
MCP ServerIntegração & APIsIntermediário
YoppaV

Twitter/X MCP Server

YoppaV/twitter-mcp

Integre sua conta X ao Claude como ferramenta de leitura com 17 endpoints

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server read-only para consultar sua conta Twitter/X via Claude, usando Playwright para interception de GraphQL. Acessa bookmarks, timeline, busca, threads, perfis, trends e artigos X com expansão automática de tweets citados e conteúdo completo de artigos long-form.

Instalação

$npx convez-ai YoppaV/twitter-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Consultar bookmarks e timeline da conta pessoal durante conversas no Claude
  • Pesquisar tweets e expandir threads com contexto completo (incluindo tweets citados)
  • Baixar mídia de tweets e artigos X para análise ou arquivamento
  • Monitorar menções, trends e engagement (likers, retweeters) sem sair do Claude

Veredito

Solução sólida para quem quer acessar dados pessoais de X via Claude sem usar a API oficial. A abordagem de sessão autenticada com Playwright é robusta, mas mantém-se read-only para evitar flagging de conta. Ideal para produtividade e pesquisa pessoal.

README

A tradução para o português deste README ainda está na fila.

twitter-mcp

tests

A read-only personal scraper for Twitter/X — packaged as two things in one repo:

  1. twitter_sdk — a Playwright-driven Python library for fetching your own logged-in bookmarks, home timeline, search results, tweet threads, user profiles, and long-form X articles. Imported as a regular package.
  2. An MCP server — exposes those endpoints as 17 tools so Claude Code and Claude Desktop can query your account during any conversation, with no separate scripts to run.

Auth is reused from a real Playwright browser session — no API keys, no official-API rate limits. Browsing is read-only by design (no posting, liking, following, or DMs) to minimize the chance of getting your account flagged.

What makes it useful: bookmarks and tweets that quote another tweet are fully expanded — the quoted tweet's text and media are fetched and merged into the result. Bookmarks pointing at a native X long-form article get the full article body (Markdown + HTML, images inlined) instead of a 140-char preview. This is what makes downstream ingestion (e.g. social-ingest) actually readable.

The 17 MCP tools

All return plain JSON, except download_media, which also returns binary content (downloaded images, viewable inline):

ToolWhat it does
auth_statusIs the session loaded? (No network call.)
get_bookmarks(limit, since_id)Your bookmarks, newest first.
get_home_timeline(limit, feed, since_id)for_you or following.
get_tweet(id_or_url, include_replies, include_quote)Focal tweet + replies + quoted.
search_tweets(query, mode, limit)Twitter search, top or latest.
get_user_profile(handle)Bio, counters, pinned tweet.
get_user_tweets(handle, limit, include_replies, include_media_only)Profile timeline.
get_x_article(id_or_url)Full body of a native X long-form article.
get_trends(category, limit)Explore tab — trending, news, sports, entertainment, for_you.
get_user_followers(handle, limit)Who follows this user (newest first).
get_user_following(handle, limit)Who this user follows.
get_user_mentions(handle, limit, mode)Tweets that mention @handle.
get_thread(id_or_url)Author-only self-reply chain from a focal tweet.
get_tweet_quotes(id_or_url, limit, mode)Quote-tweets of a tweet.
get_liking_users(id_or_url, limit)Users who liked a tweet.
get_retweeting_users(id_or_url, limit)Users who retweeted (excludes quotes).
download_media(id_or_url, source, indices, from_quoted, download_videos)Download a tweet's/article's media — photos returned inline so Claude can see them; videos/GIFs opt-in. Articles also saved as Markdown + HTML with images inlined.

Setup

Requires Python 3.10+, uv for dependency management, and ~500 MB of disk for the Chromium binary that Playwright downloads.

Install uv (one-time, skip if you already have it):

curl -LsSf https://astral.sh/uv/install.sh | sh

Then bootstrap the project:

git clone https://github.com/YoppaV/twitter-mcp
cd twitter-mcp

# 1. Create the virtualenv and install dependencies
uv venv venv                                   # creates ./venv with the right Python
uv pip install --python venv/bin/python -r requirements.txt

# 2. Install the package itself editable — needed so the MCP Inspector
#    (``mcp dev``) can load src/twitter_sdk/server.py as a single file.
uv pip install --python venv/bin/python -e .

# 3. Download the Chromium binary Playwright drives
venv/bin/python -m playwright install chromium

# 4. Configure your handle
cp .env.example .env                           # then set TWITTER_USERNAME (required)

TWITTER_USERNAME is the only mandatory value in .env — it's used to name the session file (<handle>_twitter_state.json) and auth_login refuses to run without it.

WSL2 only — if Playwright complains about missing system libs:

sudo venv/bin/python -m playwright install-deps chromium

(auth_login opens a headed Chromium window. On WSL2 this is rendered by WSLg, which ships with Windows 11 by default.)

First-time session init

The Playwright storage_state cookie file lives at ~/.config/twitter-mcp/sessions/<handle>_twitter_state.json by default (override with TWITTER_SESSION_FILE). Pre-existing files in ./sessions/ are also picked up as a fallback for backwards compatibility.

Two ways to create the session:

# (1) Interactive: open a real Chromium window and log in by hand.
venv/bin/python -m scripts.auth_login

A Chromium window opens (WSLg paints it on Windows). Log in manually — 2FA, captcha, whatever. The script waits until the auth_token + ct0 cookies appear, then persists the storage state.

# (2) Reuse a Firefox session you're already logged into.
# Close Firefox first to release the SQLite lock.
venv/bin/python -m scripts.auth_import_firefox

When the session expires, MCP tools surface a SessionExpiredError telling you to re-run auth_login. They never silently re-login.

Use as a library (twitter_sdk)

For sibling projects that just want the SDK:

uv pip install -e /path/to/twitter-mcp
import asyncio
from pathlib import Path
from twitter_sdk.browser import BrowserSession
from twitter_sdk.endpoints import bookmarks

async def main():
    session = Path.home() / ".config/twitter-mcp/sessions/yourhandle_twitter_state.json"
    browser = BrowserSession(session, idle_timeout_s=0, headless=True)
    try:
        async with browser.page() as page:
            for tweet in await bookmarks.fetch(page, limit=20):
                print(tweet.tweet_id, tweet.text[:80])
    finally:
        await browser.shutdown()

asyncio.run(main())

This is the same surface area social-ingest consumes for its Twitter pipeline. The Tweet dataclass carries a quoted field with the embedded quoted-tweet metadata and a media tuple with photo/video/gif URLs already resolved.

Use as an MCP server

Claude Code

.mcp.json is committed at the repo root. cd into this directory in Claude Code and the twitter server is auto-discovered. With TWITTER_USERNAME set in .env, the server auto-resolves the session at ~/.config/twitter-mcp/sessions/<handle>_twitter_state.json — no extra config needed. Override with TWITTER_SESSION_FILE only if your session lives somewhere else.

Restart Claude Code (or /mcp reconnect) after editing .env so the server picks up the new values. Then ask things like:

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "twitter": {
      "command": "/absolute/path/to/twitter-mcp/venv/bin/python",
      "args": ["-m", "twitter_sdk.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/twitter-mcp/src",
        "TWITTER_SESSION_FILE": "/absolute/path/to/sessions/yourhandle_twitter_state.json"
      }
    }
  }
}

Restart Claude Desktop. The tools appear in the tool picker.

Logs (Desktop): ~/Library/Logs/Claude/ (macOS).

Standalone

venv/bin/python -m twitter_sdk.server

Speaks JSON-RPC over stdio. You normally don't run this directly — Claude Code and Claude Desktop spawn it for you.

MCP Inspector

Inspect the server interactively with the bundled MCP Inspector (browse the 17 tools, fire them with arbitrary args, see raw responses):

venv/bin/mcp dev src/twitter_sdk/server.py

The mcp CLI ships with the mcp[cli] dependency, so no extra install is needed — just open the printed URL in your browser. Requires Node.js on PATH (the Inspector UI is a small Node app mcp dev spawns for you) and the editable install from setup step 2 (so mcp dev can resolve twitter_sdk as a package when it loads server.py as a single file).

Configuration

Env varDefaultWhat it does
TWITTER_SESSION_FILE~/.config/twitter-mcp/sessions/<TWITTER_USERNAME>_twitter_state.jsonPath to Playwright storage_state JSON
TWITTER_USERNAMEemptyUsed to derive session path if TWITTER_SESSION_FILE is unset
TWITTER_DOWNLOADS_DIR./downloadsWhere download_media writes fetched media
BROWSER_IDLE_TIMEOUT_S300Tear down Chromium after this many seconds idle
BROWSER_HEADLESStrueSet false to debug with a visible browser

Architecture

src/twitter_sdk/
├── server.py          FastMCP — registers the 17 tools
├── browser.py         Async Playwright singleton + idle shutdown + asyncio.Lock
├── auth.py            storage_state load + session_summary + login helpers
├── models.py          Tweet / MediaItem / XArticle / QuotedTweet / User / Trend
├── parsers.py         GraphQL → dataclass extractors (pure)
├── scraper.py         scroll_collect() + intercept_single_response()
├── downloader.py      pure httpx streaming download helper (no Playwright)
└── endpoints/
    ├── _ids.py        shared handle / tweet-id / article-id parsers
    ├── bookmarks · home · tweet · search · user · article
    ├── media          resolve_tweet_media / resolve_article_media
    ├── trends         get_trends — explore tabs
    └── social_graph   followers · following · likers · retweeters

download_media saves photos to the downloads directory (defaults to ./downloads/, override with TWITTER_DOWNLOADS_DIR) and returns them inline as viewable images so the picture itself enters the conversation. Videos/GIFs are opt-in (download_videos=True) since Claude can't watch them. For a native X article it also writes article_<id>.md and .html — the article re-rendered (headings, text, images inlined where they appear), readable offline. The default downloads directory is gitignored and treated as temporary scratch.

scraper.scroll_collect is generic over the item type — it takes (url, fragment, extractor) plus an optional key_of for deduplication. All timeline endpoints (tweets, users, trends) share that one loop.

Tests

venv/bin/python -m unittest discover tests -v

All offline. Fixture-driven (tests/fixtures/graphql_*.json) — no network, no real browser. The endpoint tests use a FakePage that records the response event handler, then dispatches synthetic Twitter GraphQL payloads through it to exercise the full path through scroll_collect().

CI runs the same suite on Python 3.10 + 3.12.

Real-network smoke

For an end-to-end check against live x.com (handy after Twitter rotates a GraphQL fragment), there's a small runner that exercises every tool with conservative limits:

venv/bin/python -m scripts.smoke_real

Takes 2-4 minutes, prints a PASS/FAIL table per tool, and exits non-zero if anything broke. Requires a valid session (see "First-time session init").

Troubleshooting

"Twitter session expired" — auth_token is no longer valid. Re-run scripts.auth_login.

A tool returns [] for everything — Twitter rotated a GraphQL operation hash. Open DevTools on x.com/<relevant-page>, find the new operation name in the */graphql/*/<Name> URL, and update the FRAGMENT constant in the matching src/twitter_sdk/endpoints/*.py file. Capture the JSON response as a new fixture and add a parser test.

Server doesn't appear in Claude Desktop — check ~/Library/Logs/Claude/mcp*.log. Most often the path in claude_desktop_config.json is wrong, or PYTHONPATH doesn't include src.

Out of RAM — lower BROWSER_IDLE_TIMEOUT_S (e.g. 60) so Chromium tears down sooner between calls.

Caveats

  • This is a personal-scale scraper of your own logged-in account. It is not a multi-tenant API. X may detect and flag bulk usage; cookies will invalidate at the platform's discretion.
  • Respect Twitter/X's Terms of Service. You are responsible for how you use the data this tool fetches.
  • No warranty, no SLA. Twitter's GraphQL surface rotates without notice — expect occasional fixture refreshes when an endpoint changes.

Out of scope

  • Writes (post, like, bookmark, follow, DM). Decided up front.
  • Cache or persistence between server restarts. Each call fetches fresh.
  • Multiple accounts simultaneously. One TWITTER_SESSION_FILE per server.

License

MIT © 2026 Juan Rodríguez Díaz de Greñu.

Ver o original no GitHub

Bom para

Relacionados