CLI 模式¶

twikit-mcp 是多模式二进制。同一个安装,三种用法:

模式	命令	何时用
MCP server(默认)	`twikit-mcp` 或 `twikit-mcp serve`	AI agent 里(Claude Code、Cursor、Cline 等),LLM 通过 stdio 发 JSON-RPC
人用 CLI	`twikit-mcp tweet 20`、`twikit-mcp user elonmusk` 等	在 shell 里想读条推 / 看个 profile / 刷下 timeline。输出是纯文本,原生中日韩文(无转义)
机器 CLI	`twikit-mcp list` / `twikit-mcp call <tool> key=value …`	shell 脚本、自动化、调试。raw JSON 输出,57 个工具全都能调

三种模式共享同一个 cookies 文件(~/.config/twitter-mcp/cookies.json)。

人用子命令¶

文本输出、位置参数、不输出 JSON。五个子命令覆盖"我就想读 X"的常见场景:

twikit-mcp tweet 20                       # 一条推漂亮打印
twikit-mcp tweet https://x.com/jack/status/20  # URL 也能用
twikit-mcp user elonmusk                  # 一个用户的 profile
twikit-mcp tl 10                          # 自己 home timeline 最近 10 条
twikit-mcp search "AI" 5                  # "AI" 的 top 5 搜索结果
twikit-mcp trends 20                      # top 20 热门话题
twikit-mcp video 1234567890               # 下载视频到 ~/Downloads/twikit-mcp/
twikit-mcp video <url> -o ~/Movies        # 自定义输出目录

video 子命令需要 yt-dlp 在 PATH 里:

uv tool install yt-dlp           # 推荐(独立环境)
# 或:pipx install yt-dlp / pip install --user yt-dlp

ffmpeg 只在你传 format=bestvideo+bestaudio 这类需要 mux 多流的 format 时才需要;默认的 best[ext=mp4] 是 X 直接给的单文件 mp4(已 mux 好),无需 ffmpeg。

终端样例输出(0.1.24+ Rich 渲染卡片 + 可点链接):

╭──────────────────────────────────────────────────────────────────────────────╮
│ Pathfinder Sports · @pathfinderSport                                         │
│ Sat Feb 21 16:55:22 +0000 2009                                               │
│ ──────────────────────────────────────────────────────────────────────────── │
│ Άρσεναλ - Σάντερλαντ: (X) 0-0 τελικό                                         │
│ ──────────────────────────────────────────────────────────────────────────── │
│ ❤ 7,269    🔁 5,473                                                          │
│ https://x.com/pathfinderSport/status/1234567890                              │
╰──────────────────────────────────────────────────────────────────────────────╯

真实终端里:作者名粗体青色、时间戳灰显、❤ 红、🔁 绿,URL 被 OSC 8 escape 包起来 — 在 iTerm2 / kitty / WezTerm / Windows Terminal / gnome-terminal ≥ 3.36 里 cmd-click 直接打开。emoji 和中日韩字符列宽正确(Rich 用 cell-aware 度量算 padding,不再像 0.1.23 那样右边框偏移)。

宽度会按终端列数自动夹到 [60, 100]。重定向到文件 / 管道,或设 NO_COLOR=1,自动回退到字节稳定的纯文本 — 形状和 0.1.22 完全一致,jq / grep / diff 都安全:

@pathfinderSport · Pathfinder Sports
Άρσεναλ - Σάντερλαντ: (X) 0-0 τελικό
❤ 7,269  🔁 5,473  · Sat Feb 21 16:55:22 +0000 2009
https://x.com/pathfinderSport/status/1234567890

这些只是同一组 MCP 工具的轻包装。需要更细的参数(product=Latest / 自定义 cursor 等)直接走 call。

机器子命令¶

`serve`(默认)¶

跑 MCP server,通过 stdio 通信。不带子命令时默认走这个 — 现有所有 mcp.json / Claude Code / Cursor 配置都不用改。

twikit-mcp           # 默认 — MCP server
twikit-mcp serve     # 显式

`list`¶

打印所有注册过的工具名,排序后每行一个。

$ twikit-mcp list
add_list_member
block_user
…
vote

`call <tool> [key=value …]`¶

调一个工具,打印 JSON 输出。

$ twikit-mcp call get_user_info screen_name=elonmusk
{"id":"44196397","screen_name":"elonmusk", …}

$ twikit-mcp call search_tweets query=AI count=5 product=Top
[…]

$ twikit-mcp call get_tweet tweet_id=20 | jq .text
"just setting up my twttr"

类型转换¶

CLI 传进来都是字符串,根据工具签名的标注 cast:

标注	转换
`str`	直通
`int` / `float`	`int(value)` / `float(value)`
`bool`	宽松匹配:`true / 1 / yes / on`(不区分大小写)→ `True`;其他 → `False`
`Optional[X]` / `X \\| None`	拆开取 `X`;空字符串 → `None`(显式 escape hatch)
其他	当字符串直通

KV 切分只切第一个 = — URL / base64 / JWT 里的额外 = 完整保留。

退出码¶

码	含义
`0`	成功
`1`	argparse / 用法错误
`2`	`ToolError`(参数校验失败或 twikit 抛了类型化异常)
其他	未捕获异常 — bug,请提 issue

Tips¶

# 管道接 jq
twikit-mcp call get_user_info screen_name=elonmusk | jq .followers_count

# cron 定期拍快照
0 10 * * 1   /usr/local/bin/twikit-mcp call get_trends category=trending count=20 \
             > "$HOME/trends/$(date +%F).json"

# 通过"未知参数"报错查看可用 args
$ twikit-mcp call get_user_info bogus=x
Unknown arg `bogus` for tool `get_user_info`. Valid args: ['screen_name', 'user_id']

所有工具(machine CLI)¶

所有注册的 MCP 工具,可通过 machine 模式 CLI 调用(twikit-mcp call <tool> key=value …)。自动生成,不会漂移。完整的参数签名和返回形状见 MCP 工具 API 参考。

推文 (Tweets)¶

共 15 个:

`bookmark_tweet`¶

Bookmark a tweet. Optionally add it to a bookmark folder.

twikit-mcp call bookmark_tweet tweet_id=20 folder_id=<folder_id>

`delete_bookmark`¶

Remove a tweet from bookmarks.

twikit-mcp call delete_bookmark tweet_id=20

`delete_retweet`¶

Un-retweet a tweet by ID.

twikit-mcp call delete_retweet tweet_id=20

`delete_tweet`¶

Delete a tweet by ID.

twikit-mcp call delete_tweet tweet_id=20

`get_bookmarks`¶

Get bookmarked tweets (paginated).

twikit-mcp call get_bookmarks count=5 cursor=<cursor>

`get_favoriters`¶

Get users who liked a tweet (paginated).

twikit-mcp call get_favoriters tweet_id=20 count=5

`get_retweeters`¶

Get users who retweeted a tweet (paginated).

twikit-mcp call get_retweeters tweet_id=20 count=5

`get_timeline`¶

Fetch home timeline tweets.

twikit-mcp call get_timeline count=5

`get_tweet`¶

Fetch a tweet by ID.

twikit-mcp call get_tweet tweet_id=20

`get_tweet_replies`¶

Fetch replies (comments) to a tweet (issue #94).

twikit-mcp call get_tweet_replies tweet_id=20 cursor=<cursor>

`like_tweet`¶

Like a tweet by ID.

twikit-mcp call like_tweet tweet_id=20

`retweet`¶

Retweet a tweet by ID.

twikit-mcp call retweet tweet_id=20

`search_tweets`¶

Search tweets.

twikit-mcp call search_tweets query="AI" count=5

`send_tweet`¶

Send a tweet. Optionally reply to a tweet by ID.

twikit-mcp call send_tweet text="hello world" reply_to=<reply_to>

`unfavorite_tweet`¶

Unlike a tweet by ID.

twikit-mcp call unfavorite_tweet tweet_id=20

用户 (Users)¶

共 11 个:

`block_user`¶

Block a user by screen name.

twikit-mcp call block_user screen_name=elonmusk

`follow_user`¶

Follow a user by screen name.

twikit-mcp call follow_user screen_name=elonmusk

`get_user_followers`¶

Get a user's followers list.

twikit-mcp call get_user_followers screen_name=elonmusk user_id=<user_id>

`get_user_following`¶

Get accounts that a user follows (their following list).

twikit-mcp call get_user_following screen_name=elonmusk user_id=<user_id>

`get_user_info`¶

Get a user's profile metadata by screen name OR numeric user ID.

twikit-mcp call get_user_info screen_name=elonmusk user_id=<user_id>

`get_user_tweets`¶

Get recent tweets from a specific user.

twikit-mcp call get_user_tweets screen_name=elonmusk count=5

`mute_user`¶

Mute a user by screen name.

twikit-mcp call mute_user screen_name=elonmusk

`search_user`¶

Search for users by query (paginated).

twikit-mcp call search_user query="AI" count=5

`unblock_user`¶

Unblock a user by screen name.

twikit-mcp call unblock_user screen_name=elonmusk

`unfollow_user`¶

Unfollow a user by screen name.

twikit-mcp call unfollow_user screen_name=elonmusk

`unmute_user`¶

Unmute a user by screen name.

twikit-mcp call unmute_user screen_name=elonmusk

列表 (Lists)¶

共 9 个:

`add_list_member`¶

Add a user to a Twitter List.

twikit-mcp call add_list_member list_id=1234567890 screen_name=elonmusk

`create_list`¶

Create a new Twitter List.

twikit-mcp call create_list name=<name> description=<description>

`edit_list`¶

Edit a Twitter List's metadata.

twikit-mcp call edit_list list_id=1234567890 name=<name>

`get_list`¶

Get a Twitter List by ID.

twikit-mcp call get_list list_id=1234567890

`get_list_members`¶

Get members of a Twitter List (paginated).

twikit-mcp call get_list_members list_id=1234567890 count=5

`get_list_subscribers`¶

Get subscribers of a Twitter List (paginated).

twikit-mcp call get_list_subscribers list_id=1234567890 count=5

`get_list_tweets`¶

Get tweets from a Twitter List (paginated).

twikit-mcp call get_list_tweets list_id=1234567890 count=5

`get_lists`¶

Get the authenticated user's Twitter Lists (paginated).

twikit-mcp call get_lists count=5 cursor=<cursor>

`remove_list_member`¶

Remove a user from a Twitter List.

twikit-mcp call remove_list_member list_id=1234567890 screen_name=elonmusk

社群 (Communities)¶

共 10 个:

`get_communities_timeline`¶

Get tweets from communities the authenticated user has joined (paginated).

twikit-mcp call get_communities_timeline count=5 cursor=<cursor>

`get_community`¶

Get a Twitter Community by ID.

twikit-mcp call get_community community_id=1234567890

`get_community_members`¶

Get members of a Twitter Community (paginated).

twikit-mcp call get_community_members community_id=1234567890 count=5

`get_community_moderators`¶

Get moderators of a Twitter Community (paginated).

twikit-mcp call get_community_moderators community_id=1234567890 count=5

`get_community_tweets`¶

Get tweets from a Twitter Community (paginated).

twikit-mcp call get_community_tweets community_id=1234567890 tweet_type=<tweet_type>

`join_community`¶

Join a Twitter Community.

twikit-mcp call join_community community_id=1234567890

`leave_community`¶

Leave a Twitter Community.

twikit-mcp call leave_community community_id=1234567890

`request_to_join_community`¶

Request to join a Twitter Community.

twikit-mcp call request_to_join_community community_id=1234567890 answer=<answer>

`search_community`¶

Search for Twitter Communities by query (paginated).

twikit-mcp call search_community query="AI" cursor=<cursor>

`search_community_tweet`¶

Search tweets within a Twitter Community (paginated).

twikit-mcp call search_community_tweet community_id=1234567890 query="AI"

文章 (Articles)¶

共 2 个:

`get_article`¶

Fetch an X Article (long-form post) by rest_id or URL.

twikit-mcp call get_article article_id=<article_id> format=<format>

`get_article_preview`¶

Get title/preview/cover of an X Article embedded in a tweet.

twikit-mcp call get_article_preview tweet_id=20

私信 (DMs)¶

共 4 个:

`delete_dm`¶

Delete a direct message by ID.

twikit-mcp call delete_dm message_id=<message_id>

`get_dm_history`¶

Get DM conversation history with a user.

twikit-mcp call get_dm_history screen_name=elonmusk max_id=<max_id>

`send_dm`¶

Send a direct message to a user by screen name.

twikit-mcp call send_dm screen_name=elonmusk text="hello world"

`send_dm_to_group`¶

Send a direct message to a group conversation.

twikit-mcp call send_dm_to_group group_id=<group_id> text="hello world"

发现与通知¶

共 2 个:

`get_notifications`¶

Fetch notifications (paginated).

twikit-mcp call get_notifications notification_type=<notification_type> count=5

`get_trends`¶

Get trending topics by category.

twikit-mcp call get_trends category=<category> count=5

定时推文与投票¶

共 5 个:

`create_poll`¶

Create an X poll and return its card URI.

twikit-mcp call create_poll choices=<choices> duration_minutes=100

`create_scheduled_tweet`¶

Schedule a tweet to be posted at a future Unix timestamp.

twikit-mcp call create_scheduled_tweet scheduled_at=100 text="hello world"

`delete_scheduled_tweet`¶

Delete a scheduled tweet by its scheduled tweet ID.

twikit-mcp call delete_scheduled_tweet scheduled_tweet_id=<scheduled_tweet_id>

`get_scheduled_tweets`¶

Return all scheduled tweets for the authenticated user.

twikit-mcp call get_scheduled_tweets

`vote`¶

Vote on an X poll.

twikit-mcp call vote selected_choice=<selected_choice> card_uri=<card_uri> tweet_id=20 card_name=<card_name>

其他¶

共 1 个:

`download_tweet_video`¶

Download video(s) attached to a tweet via yt-dlp.

twikit-mcp call download_tweet_video tweet_id=20 output_dir=<output_dir>

CLI 模式¶

人用子命令¶

机器子命令¶

serve(默认)¶

list¶

call <tool> [key=value …]¶

类型转换¶

退出码¶

Tips¶

所有工具(machine CLI)¶

推文 (Tweets)¶

bookmark_tweet¶

delete_bookmark¶

delete_retweet¶

delete_tweet¶

get_bookmarks¶

get_favoriters¶

get_retweeters¶

get_timeline¶

get_tweet¶

get_tweet_replies¶

like_tweet¶

retweet¶

search_tweets¶

send_tweet¶

unfavorite_tweet¶

用户 (Users)¶

block_user¶

follow_user¶

get_user_followers¶

get_user_following¶

get_user_info¶

get_user_tweets¶

mute_user¶

search_user¶

unblock_user¶

unfollow_user¶

unmute_user¶

列表 (Lists)¶

add_list_member¶

create_list¶

edit_list¶

get_list¶

get_list_members¶

get_list_subscribers¶

get_list_tweets¶

get_lists¶

remove_list_member¶