CLI モード¶

twikit-mcp はマルチモードのバイナリです。同じインストールで、3 種類の使い方:

モード	コマンド	使う場面
MCP サーバー(デフォルト)	`twikit-mcp` または `twikit-mcp serve`	AI エージェント(Claude Code、Cursor、Cline など)、LLM が stdio 経由で JSON-RPC を送る
ヒューマン CLI	`twikit-mcp tweet 20`、`twikit-mcp user elonmusk` など	シェルでツイート / プロフィール / タイムラインを直接読みたいとき。出力はプレーンテキスト、ネイティブ Unicode
マシン CLI	`twikit-mcp list` / `twikit-mcp call <tool> key=value …`	シェルスクリプト、自動化、デバッグ。生 JSON 出力、57 ツール全部呼べる

3 モードとも同じ cookies ファイル(~/.config/twitter-mcp/cookies.json)を共有します。

ヒューマン用サブコマンド¶

整形済みテキスト、位置引数、JSON なし。「X を読みたい」の典型ケースを 5 つカバー:

twikit-mcp tweet 20                       # 1 ツイートを整形表示
twikit-mcp tweet https://x.com/jack/status/20  # URL も可
twikit-mcp user elonmusk                  # 1 プロフィール
twikit-mcp tl 10                          # 自分のホームタイムライン直近 10 件
twikit-mcp search "AI" 5                  # "AI" のトップ 5 検索結果
twikit-mcp trends 20                      # トップ 20 トレンド
twikit-mcp video 1234567890               # 動画を ~/Downloads/twikit-mcp/ にダウンロード
twikit-mcp video <url> -o ~/Movies        # 出力ディレクトリを指定

video サブコマンドは PATH に yt-dlp が必要:

uv tool install yt-dlp           # 推奨(独立環境)
# または:pipx install yt-dlp / pip install --user yt-dlp

ffmpeg は format=bestvideo+bestaudio のような複数ストリームのマージが必要な format を渡したときだけ必要です。デフォルトの best[ext=mp4] は X が直接配信する単一ファイル mp4(マージ済み)なので、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 エスケープで包まれます — iTerm2 / kitty / WezTerm / Windows Terminal / gnome-terminal ≥ 3.36 で cmd-クリックすればブラウザで開きます。emoji と CJK の行は列幅が正しい(Rich の cell-aware 計測でパディング — 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 サーバーを stdio で起動。サブコマンドなしのデフォルト動作 — 既存の mcp.json / Claude Code / Cursor 設定はそのまま動きます。

twikit-mcp           # デフォルト — MCP サーバー
twikit-mcp serve     # 明示的

`list`¶

登録されたツール名を一行ずつソートして出力。

$ twikit-mcp list
add_list_member
block_user
…
vote

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

ツールを 1 回呼び出し、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 引数は文字列で渡されるので、ツールのアノテーションに合わせて変換:

アノテーション	変換
`str`	そのまま
`int` / `float`	`int(value)` / `float(value)`
`bool`	緩い一致:`true / 1 / yes / on`(大文字小文字不問)→ `True`;それ以外 → `False`
`Optional[X]` / `X \\| None`	`X` にアンラップ;空文字列 → `None` を明示的にエスケープ
その他	文字列のままパススルー

KV 分割は最初の = のみ — URL / base64 / JWT に含まれる追加の = は保持されます。

終了コード¶

Code	意味
`0`	成功
`1`	argparse / 使用法エラー
`2`	`ToolError`(引数バリデーション失敗 or twikit が型付き例外を投げた)
その他	キャッチされなかった例外 — バグなので 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']

すべてのツール(マシン CLI)¶

すべての登録済み MCP ツール、マシンモード 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

DM¶

全 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¶

すべてのツール(マシン 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¶