Skip to content

twikit-mcp

Twitter/X MCP server + CLI — no API key needed.

PyPI CI License: MIT

An MCP server that lets Claude (or any MCP-compatible AI agent) interact with Twitter/X using browser cookies. The same twikit-mcp binary doubles as a CLI for shell scripts and debugging.

What's new in 0.1.33

  • Drop the 200-char text truncation — get_timeline / search_tweets / get_user_tweets / get_bookmarks / get_list_tweets / get_scheduled_tweets / get_community_tweets / get_communities_timeline / search_community_tweet no longer cut tweet text at 200 characters. get_tweet and get_tweet_replies also switch to Tweet.full_text, which returns the long-form text (up to 4000 chars) for X note tweets. Compact responses are user-controlled via count. (closes #97)
  • get_article_preview distinguishes quote tweets — when the input is a quote tweet, the error now says "this is a quote tweet, not an article. Use get_tweet to read the quoted tweet content" instead of the generic "does not embed an article".

Upgrade with uv tool upgrade twikit-mcp (or pip install --upgrade twikit-mcp).

What's new in 0.1.32

  • Read tweet replies — new get_tweet_replies(tweet_id, cursor=None) tool fetches the comments / discussion under a tweet. Uses X's TweetDetail GraphQL via vendored twikit; one page per call with next_cursor for more. Returns the same compact reply shape as get_user_tweets / get_timeline. (closes #94)

What's new in 0.1.31

  • Per-client install matrix in docs — new Install page walks through registering twikit-mcp with Claude Code / Claude Desktop / Cursor / Windsurf / Cline / opencode (config file path + JSON snippet, ≤ 12 lines per client). Single canonical install command (uv tool install twikit-mcp); JSON shape is universal across clients. (closes #92)

What's new in 0.1.30

  • Localized API docs page — /zh/api/ and /ja/api/ now show Chinese / Japanese chrome (title, intro, table headers, section labels) instead of falling back to English. Tool docstrings stay native (Python source) — same trade-off mkdocstrings makes. (closes #90)

What's new in 0.1.29

  • Community + article-preview reliability — get_community / get_community_tweets / get_community_members / get_community_moderators / search_community_tweet no longer crash with KeyError: 'rest_id' / IndexError. get_article_preview now surfaces a clean ToolError instead of leaking HTTPStatusError when the syndication endpoint returns 404 for a stale article. Defensive .get() parsing in _vendor/twikit/community.py + client.py. Closes issue #76 — T_DRIFT is now empty in live-smoke.yml. (issue #76 parts 2 + 3)

What's new in 0.1.28

  • List-tool reliability — get_list / get_list_tweets / get_list_members / get_list_subscribers no longer crash with KeyError: 'created_at' / IndexError / Invalid list id on burner-gated responses. Defensive parsing in _vendor/twikit/list.py + client.py: missing fields return None/""/0, empty entries return empty Result. Live-smoke now catches future regressions of these classes (no more T_DRIFT tolerance for the list path). (issue #76 part 1)

What's new in 0.1.27

  • Download tweet videos via yt-dlp — new download_tweet_video MCP tool + twikit-mcp video <id> CLI subcommand. Saves to ~/Downloads/twikit-mcp/ by default. Authenticated via your existing cookies.json. Requires yt-dlp on PATH (uv tool install yt-dlp); ffmpeg only needed if you pass a separate-stream format like bestvideo+bestaudio. (closes #84)

What's new in 0.1.26

  • Quote tweet visibility on get_tweet — the response now includes is_quote_status, quoted_id, quoted_author, and quoted_text when the tweet quote-retweets another. Agents can now show the quoted text inline without an extra get_tweet round-trip — the data is already in the same GraphQL response, we just expose it. (closes #82)

What's new in 0.1.25

  • Conversation context on get_tweet — the response now includes in_reply_to (parent tweet ID when the tweet is a reply) and conversation_id (root tweet ID of the thread). Agents can now reconstruct thread context from a single tweet without needing the user to paste the parent link. (closes #77)

What's new in 0.1.24

  • Rich-rendered cards — the terminal cards from 0.1.23 are now produced by Rich, giving correct cell-width math for emoji + CJK (no more right-border drift on ❤ 🔁 lines), and OSC 8 clickable hyperlinks for tweet / profile / bio URLs in iTerm2, kitty, WezTerm, Windows Terminal, gnome-terminal ≥ 3.36, etc. The trends list is now a proper table.
  • Plain (non-TTY) output unchanged: | jq / > file / NO_COLOR=1 consumers stay byte-stable.

What's new in 0.1.23

  • ASCII Twitter-card UI — twikit-mcp tweet, user, tl, search, trends now render box-drawing cards in your terminal (bold author, dim timestamps, separators between body / counts / URL). Piping to a file or another command, or setting NO_COLOR=1, auto-falls-back to the previous byte-stable plain text. See CLI mode for samples.

What's new in 0.1.22

  • Human-friendly CLI subcommands — read tweets / profiles / timeline / search / trends straight from your terminal:
twikit-mcp tweet 20
twikit-mcp user elonmusk
twikit-mcp tl 10

Plain text output, native unicode, sensible defaults. See the CLI mode page. - UTF-8 outputs end-to-end — no more \uXXXX escapes. Greek / 中文 / 日本語 / emoji all flow through tools as readable text. - Tri-lingual docs site — this very page; switch language in the top bar.

What you get

  • 57 tools covering tweets, users, lists, communities, scheduled tweets + polls, DMs, articles, search, trends, notifications.
  • Browser-cookie auth — copy ct0 + auth_token from your X session, you're authenticated.
  • Two transports, one binary — MCP server (default) for AI agents; twikit-mcp call <tool> CLI for shells.
  • Vendored twikit with project-specific defensive patches.

Where to go

  • CLI mode — subcommands, type coercion, exit codes, examples.
  • MCP Tools API — auto-generated reference: every tool's signature + docstring + CLI example, kept in sync with code.
  • Technical design — internals (currently 中文 only — translation welcome).
  • Vendoring twikit — every patch and the issue that motivated it (currently 中文 only).
  • GitHub repo — README has full install / quickstart in three languages.

Quick install

# 1. Drop your X cookies into ~/.config/twitter-mcp/cookies.json
mkdir -p ~/.config/twitter-mcp
cat > ~/.config/twitter-mcp/cookies.json <<'EOF'
{"ct0": "...", "auth_token": "..."}
EOF
chmod 600 ~/.config/twitter-mcp/cookies.json

# 2. Install (recommended for daily use)
uv tool install twikit-mcp

# 3. Register with Claude Code
claude mcp add twitter -s user \
  -e "TWITTER_COOKIES=$HOME/.config/twitter-mcp/cookies.json" \
  -- twikit-mcp

Use uv tool upgrade twikit-mcp to update; full alternatives (uvx / pip / pipx) on the GitHub README.