CLI mode¶

twikit-mcp is a multi-mode binary. Same install, three flavors:

Mode	Command	When
MCP server (default)	`twikit-mcp` or `twikit-mcp serve`	Inside an AI agent (Claude Code, Cursor, Cline, …). LLM sends JSON-RPC over stdio.
Human-friendly CLI	`twikit-mcp tweet 20`, `twikit-mcp user elonmusk`, etc.	You're at a shell, you want to read a tweet / profile / timeline. Output is plain text, native unicode.
Machine CLI	`twikit-mcp list` / `twikit-mcp call <tool> key=value …`	Shell scripts, automation, debugging. Raw JSON output, every one of the 57 tools available.

All three share the same cookies file (~/.config/twitter-mcp/cookies.json).

Human-friendly subcommands¶

Pretty-printed text output, positional args, no JSON. Five subcommands cover the common "I want to read X" cases:

twikit-mcp tweet 20                       # one tweet pretty-printed
twikit-mcp tweet https://x.com/jack/status/20  # URL works too
twikit-mcp user elonmusk                  # one profile
twikit-mcp tl 10                          # last 10 from your home timeline
twikit-mcp search "AI" 5                  # 5 top search results
twikit-mcp trends 20                      # top 20 trending topics
twikit-mcp video 1234567890               # download video to ~/Downloads/twikit-mcp/
twikit-mcp video <url> -o ~/Movies        # custom output dir

The video subcommand requires yt-dlp on PATH:

uv tool install yt-dlp           # recommended (isolated)
# or: pipx install yt-dlp / pip install --user yt-dlp

ffmpeg is only needed if you pass a separate-stream format like format=bestvideo+bestaudio; the default best[ext=mp4] is single-file muxed mp4 from X and works without ffmpeg.

Sample output in a terminal (0.1.24+ Rich-rendered card with clickable links):

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

In a real terminal: the author handle is bold cyan, the timestamp is dim, ❤ is red, 🔁 is green, and the URL is wrapped in an OSC 8 escape so cmd-clicking opens it in your browser (works in iTerm2, kitty, WezTerm, Windows Terminal, gnome-terminal ≥ 3.36). Emoji and CJK lines are width-correct — Rich's cell-aware measurement is used for padding, no border drift.

Width is clamped to your terminal columns (between 60 and 100). Piping to a file or another command, or setting NO_COLOR=1, auto-falls-back to byte-stable plain text — same shape as 0.1.22, safe for jq/grep/diffing:

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

These are wrappers over the same MCP tools; if you need different args (product=Latest, custom cursor, etc.), drop down to call.

Machine subcommands¶

`serve` (default)¶

Run the MCP server over stdio. Default when no subcommand given — every existing mcp.json / Claude Code / Cursor config keeps working unchanged.

twikit-mcp           # default — MCP server
twikit-mcp serve     # explicit

`list`¶

Print all registered tool names, sorted, one per line.

$ twikit-mcp list
add_list_member
block_user
…
vote

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

Invoke one tool, print its JSON output.

$ 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"

Type coercion¶

CLI args are strings; we cast to the tool's annotated types:

Annotation	Coercion
`str`	passthrough
`int` / `float`	`int(value)` / `float(value)`
`bool`	loose: `true / 1 / yes / on` (case-insensitive) → `True`; else `False`
`Optional[X]` / `X \\| None`	unwrap to `X`; empty string → `None` explicitly
anything else	passthrough as raw string

KV split is on the first = only — URLs / base64 / JWTs with extra = survive.

Exit codes¶

Code	Meaning
`0`	Success
`1`	Argparse / usage error
`2`	`ToolError` (validation rejected the input or twikit raised typed exception)
Other	Uncaught exception — bug, please file an issue

Tips¶

# Pipe to jq
twikit-mcp call get_user_info screen_name=elonmusk | jq .followers_count

# Cron a snapshot
0 10 * * 1   /usr/local/bin/twikit-mcp call get_trends category=trending count=20 \
             > "$HOME/trends/$(date +%F).json"

# Discover args via 'unknown arg' error
$ twikit-mcp call get_user_info bogus=x
Unknown arg `bogus` for tool `get_user_info`. Valid args: ['screen_name', 'user_id']

All tools (machine CLI)¶

All registered MCP tools, callable via the machine-mode CLI (twikit-mcp call <tool> key=value …). Auto-generated from the live tool registry — never drifts from code. For full argument signatures + return shapes, see the MCP Tools API reference.

Tweets¶

15 tool(s):

`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 tool(s):

`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 tool(s):

`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 tool(s):

`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 tool(s):

`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

Direct Messages¶

4 tool(s):

`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"

Discovery & notifications¶

2 tool(s):

`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

Scheduled tweets & polls¶

5 tool(s):

`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>

Other¶

1 tool(s):

`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 mode¶

Human-friendly subcommands¶

Machine subcommands¶

serve (default)¶

list¶

call <tool> [key=value …]¶

Type coercion¶

Exit codes¶

Tips¶

All tools (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¶