MCP 工具 API 参考¶
在文档构建时,从 twitter_mcp.server 里的 @mcp.tool() 装饰函数自动生成。共 59 个工具。每个工具下面都同时给出 MCP 和 CLI 两种调用形式。
| 形式 | 何时用 |
|---|---|
| MCP | 在 AI agent(Claude Code、Cursor 等)里 — LLM 自己选工具并从你的 prompt 里填参数。 |
| CLI | shell 脚本、调试、自动化。twikit-mcp call <tool> key=value … — 参数名一样,类型从字符串转换。 |
工具的 docstring 是真理之源 — 如果下面某段看起来不对,改 twitter_mcp/server.py 里的 docstring,下一次构建就会同步过来。
推文 (Tweets)¶
bookmark_tweet¶
Bookmark a tweet. Optionally add it to a bookmark folder.
Args: tweet_id: The tweet ID to bookmark. folder_id: Optional bookmark folder ID.
CLI:
delete_bookmark¶
Remove a tweet from bookmarks.
Args: tweet_id: The tweet ID to un-bookmark.
CLI:
delete_retweet¶
Un-retweet a tweet by ID.
Args: tweet_id: The tweet ID to un-retweet.
CLI:
delete_tweet¶
Delete a tweet by ID.
Args: tweet_id: The tweet ID to delete.
CLI:
get_bookmarks¶
Get bookmarked tweets (paginated).
Args:
count: Number of bookmarks to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_favoriters¶
Get users who liked a tweet (paginated).
Args:
tweet_id: The tweet ID.
count: Number of users to fetch (default 40, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_retweeters¶
Get users who retweeted a tweet (paginated).
Args:
tweet_id: The tweet ID.
count: Number of users to fetch (default 40, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_timeline¶
Fetch home timeline tweets.
Args: count: Number of tweets to fetch (default 20).
CLI:
get_tweet¶
Fetch a tweet by ID.
Args: tweet_id: The tweet ID (numeric string) or full URL.
CLI:
get_tweet_replies¶
Fetch replies (comments) to a tweet (issue #94).
Uses X's TweetDetail GraphQL endpoint via vendored twikit's
Client.get_tweet_by_id, which populates tweet.replies as a
paginated Result[Tweet]. One page per call; pass the returned
next_cursor to fetch more.
Args:
tweet_id: The tweet ID (numeric string) or full URL.
cursor: Pagination cursor from a previous response's
next_cursor; omit for the first page.
Returns: JSON with tweet_id, replies (compact list — id/author/text/ created_at/likes/retweets), next_cursor, count.
CLI:
like_tweet¶
Like a tweet by ID.
Args: tweet_id: The tweet ID.
CLI:
retweet¶
Retweet a tweet by ID.
Args: tweet_id: The tweet ID.
CLI:
search_tweets¶
Search tweets.
Args: query: Search query string. count: Number of results (default 20). product: "Latest" or "Top" (default "Latest").
CLI:
send_tweet¶
Send a tweet. Optionally reply to a tweet by ID.
Args: text: Tweet content (max 280 chars). reply_to: Optional tweet ID to reply to.
CLI:
unfavorite_tweet¶
Unlike a tweet by ID.
Args: tweet_id: The tweet ID to unlike.
CLI:
用户 (Users)¶
block_user¶
Block a user by screen name.
Note: X aggressively rate-limits / risk-scans block + mute. Avoid bulk usage or your account may be temporarily restricted.
Args: screen_name: Twitter username (without @).
CLI:
follow_user¶
Follow a user by screen name.
Note: X aggressively rate-limits follow / unfollow — avoid bulk usage or your account may be temporarily restricted.
Args: screen_name: Twitter username (without @).
CLI:
get_user_followers¶
get_user_followers(screen_name: Union = None, user_id: Union = None, count: int = 20, cursor: Union = None)
Get a user's followers list.
Note: X aggressively rate-limits follower / following requests — use
sparingly, paginate via cursor, don't loop without backoff.
Caller must provide exactly one of screen_name / user_id.
Args:
screen_name: Twitter username (without @).
user_id: Twitter numeric user ID.
count: Number of followers to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_user_following¶
get_user_following(screen_name: Union = None, user_id: Union = None, count: int = 20, cursor: Union = None)
Get accounts that a user follows (their following list).
Note: X aggressively rate-limits follower / following requests — use
sparingly, paginate via cursor, don't loop without backoff.
Caller must provide exactly one of screen_name / user_id.
Args:
screen_name: Twitter username (without @).
user_id: Twitter numeric user ID.
count: Number to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_user_info¶
Get a user's profile metadata by screen name OR numeric user ID.
Caller must provide exactly one of screen_name / user_id.
Args: screen_name: Twitter username (without @). user_id: Twitter numeric user ID.
CLI:
get_user_tweets¶
Get recent tweets from a specific user.
Args: screen_name: Twitter username (without @). count: Number of tweets to fetch (default 20).
CLI:
mute_user¶
Mute a user by screen name.
Note: X aggressively rate-limits / risk-scans block + mute. Avoid bulk usage or your account may be temporarily restricted.
Args: screen_name: Twitter username (without @).
CLI:
search_user¶
Search for users by query (paginated).
Args:
query: Search query string.
count: Number of users to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
unblock_user¶
Unblock a user by screen name.
Note: X aggressively rate-limits / risk-scans block + mute. Avoid bulk usage or your account may be temporarily restricted.
Args: screen_name: Twitter username (without @).
CLI:
unfollow_user¶
Unfollow a user by screen name.
Note: X aggressively rate-limits follow / unfollow — avoid bulk usage or your account may be temporarily restricted.
Args: screen_name: Twitter username (without @).
CLI:
unmute_user¶
Unmute a user by screen name.
Note: X aggressively rate-limits / risk-scans block + mute. Avoid bulk usage or your account may be temporarily restricted.
Args: screen_name: Twitter username (without @).
CLI:
列表 (Lists)¶
add_list_member¶
Add a user to a Twitter List.
Caller must provide exactly one of screen_name / user_id.
Args: list_id: The list ID (required). screen_name: Twitter username (without @). user_id: Twitter numeric user ID.
CLI:
create_list¶
Create a new Twitter List.
Args: name: The name for the new list (required, must not be empty). description: Description for the list (default empty). is_private: If True, the list is private (default False = public).
CLI:
edit_list¶
Edit a Twitter List's metadata.
At least one of name, description, or is_private must be provided.
Pass an empty string for description to clear it.
Args: list_id: The list ID (required). name: New name for the list. description: New description (empty string clears it). is_private: True to make private, False to make public.
CLI:
get_list¶
Get a Twitter List by ID.
Args: list_id: The list ID.
CLI:
get_list_members¶
Get members of a Twitter List (paginated).
Args:
list_id: The list ID.
count: Number of members to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_list_subscribers¶
Get subscribers of a Twitter List (paginated).
Args:
list_id: The list ID.
count: Number of subscribers to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_list_tweets¶
Get tweets from a Twitter List (paginated).
Args:
list_id: The list ID.
count: Number of tweets to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_lists¶
Get the authenticated user's Twitter Lists (paginated).
Args:
count: Number of lists to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
remove_list_member¶
Remove a user from a Twitter List.
Caller must provide exactly one of screen_name / user_id.
Args: list_id: The list ID (required). screen_name: Twitter username (without @). user_id: Twitter numeric user ID.
CLI:
社群 (Communities)¶
get_communities_timeline¶
Get tweets from communities the authenticated user has joined (paginated).
Args:
count: Number of tweets to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_community¶
Get a Twitter Community by ID.
Args: community_id: The community ID.
CLI:
get_community_members¶
Get members of a Twitter Community (paginated).
Args:
community_id: The community ID.
count: Number of members to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_community_moderators¶
Get moderators of a Twitter Community (paginated).
Args:
community_id: The community ID.
count: Number of moderators to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_community_tweets¶
Get tweets from a Twitter Community (paginated).
Args:
community_id: The community ID.
tweet_type: One of "Top", "Latest", or "Media".
count: Number of tweets to fetch (default 40, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
join_community¶
Join a Twitter Community.
Args: community_id: The community ID to join.
CLI:
leave_community¶
Leave a Twitter Community.
Args: community_id: The community ID to leave.
CLI:
request_to_join_community¶
Request to join a Twitter Community.
For communities with restricted join policies that require moderator
approval, an answer to the join request question may be required.
Args: community_id: The community ID to request to join. answer: Optional answer to the join request question (required for some communities with moderator approval policy).
CLI:
search_community¶
Search for Twitter Communities by query (paginated).
Note: twikit's search_community does not support a count parameter.
Args:
query: Search query string.
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
search_community_tweet¶
Search tweets within a Twitter Community (paginated).
Args:
community_id: The community ID.
query: Search query string.
count: Number of tweets to fetch (default 20, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
文章 (Articles)¶
get_article¶
Fetch an X Article (long-form post) by rest_id or URL.
Two-hop reader flow (issue #10):
ArticleRedirectScreenQueryresolves the article rest_id to the underlying tweet rest_id.TweetResultByRestId(twikit's existing helper) fetches the tweet with article fieldToggles enabled. The body lives attweet.article.article_results.result.
Requires authentication via cookies — same as every other authenticated tool here. No env-var setup.
Args:
article_id: Article rest_id (numeric string) or full /i/article/
CLI:
get_article_preview¶
Get title/preview/cover of an X Article embedded in a tweet.
Uses X's public syndication endpoint — no authentication required.
Args: tweet_id: ID (numeric string) or full URL of a tweet that links to an article.
CLI:
私信 (DMs)¶
delete_dm¶
Delete a direct message by ID.
Note: Deletes a PRIVATE message. Do not bulk-call. X has aggressive anti-spam on DMs and may suspend the account.
Args: message_id: The message ID to delete.
CLI:
get_dm_history¶
Get DM conversation history with a user.
Note: Retrieves PRIVATE messages. Do not bulk-call. X has aggressive anti-spam on DMs and may suspend the account.
Args:
screen_name: Twitter username (without @).
max_id: If specified, retrieves messages older than this ID (for pagination).
Pass the value from a previous response's next_cursor here on the
next call to walk further back in time.
CLI:
send_dm¶
Send a direct message to a user by screen name.
Note: Sends a PRIVATE message. Do not bulk-call. X has aggressive anti-spam on DMs and may suspend the account.
Args: screen_name: Twitter username (without @) to send the DM to. text: Message content (required, must not be empty). media_id: Optional media ID to attach.
CLI:
send_dm_to_group¶
Send a direct message to a group conversation.
Note: Sends a PRIVATE message. Do not bulk-call. X has aggressive anti-spam on DMs and may suspend the account.
Args: group_id: The group conversation ID. text: Message content (required, must not be empty). media_id: Optional media ID to attach.
CLI:
发现与通知¶
get_notifications¶
Fetch notifications (paginated).
Args:
notification_type: One of "All", "Verified", "Mentions" (default "All").
count: Number to fetch (default 40, max 100).
cursor: Pagination cursor from a previous response's next_cursor.
CLI:
get_trends¶
Get trending topics by category.
Args: category: One of "trending", "for-you", "news", "sports", "entertainment" (default "trending"). count: Number of trends to fetch (default 20).
CLI:
定时推文与投票¶
create_poll¶
Create an X poll and return its card URI.
X polls have 2-4 choices and a duration in minutes. Pass the returned card_uri to send_tweet's poll_uri parameter to attach the poll.
Args: choices: Poll choices (2-4 entries required; each must be non-empty). duration_minutes: Poll duration in minutes (must be > 0).
CLI:
create_scheduled_tweet¶
Schedule a tweet to be posted at a future Unix timestamp.
Scheduled tweets follow X's standard rate limits, no special caveats needed.
Args: scheduled_at: Unix epoch seconds when the tweet should be posted (must be in the future). text: Tweet text. At least one of text or media_ids must be provided. media_ids: List of media IDs to attach to the scheduled tweet.
CLI:
delete_scheduled_tweet¶
Delete a scheduled tweet by its scheduled tweet ID.
Scheduled tweets follow X's standard rate limits, no special caveats needed.
Args: scheduled_tweet_id: The ID of the scheduled tweet (from create_scheduled_tweet or get_scheduled_tweets). This is NOT a regular tweet ID.
CLI:
get_scheduled_tweets¶
Return all scheduled tweets for the authenticated user.
Note: returns the FULL list in one call — twikit's API does not paginate scheduled tweets. This is fine in practice since X caps scheduled tweets per account at a small number.
Scheduled tweets follow X's standard rate limits, no special caveats needed.
CLI:
vote¶
Vote on an X poll.
X polls have 2-4 choices and a duration in minutes. The card_uri and card_name come from the tweet's poll card metadata (obtainable via get_tweet).
Args: selected_choice: The label of the choice to vote for (must be non-empty). card_uri: The poll card URI (from the tweet's poll card metadata). tweet_id: The ID of the tweet containing the poll. card_name: The name of the poll card (from the tweet's poll card metadata).
CLI:
twikit-mcp call vote selected_choice=<selected_choice> card_uri=<card_uri> tweet_id=20 card_name=<card_name>
其他¶
download_tweet_video¶
Download video(s) attached to a tweet via yt-dlp.
Args: tweet_id: Tweet ID (numeric string) or full URL. output_dir: Where to save. Default: $TWIKIT_DOWNLOAD_DIR or ~/Downloads/twikit-mcp/. format: yt-dlp format selector. Default "best[ext=mp4]" (single muxed mp4, no ffmpeg required). Pass "bestvideo+bestaudio" for separate-stream max-quality merge (requires ffmpeg).
Returns: JSON with path, size_bytes, duration_sec, format, width, height, url, tweet_id. Raises ToolError if yt-dlp / ffmpeg is missing, the tweet has no video, or download fails.
CLI: