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.

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 @).

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

Args: tweet_id: The tweet ID to bookmark. folder_id: Optional bookmark folder ID.

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).

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).

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.

Remove a tweet from bookmarks.

Args: tweet_id: The tweet ID to un-bookmark.

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.

Un-retweet a tweet by ID.

Args: tweet_id: The tweet ID to un-retweet.

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.

Delete a tweet by ID.

Args: tweet_id: The tweet ID to delete.

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.

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.

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 @).

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

Two-hop reader flow (issue #10):

1. ArticleRedirectScreenQuery resolves the article rest_id to the underlying tweet rest_id.

2. TweetResultByRestId (twikit's existing helper) fetches the tweet with article fieldToggles enabled. The body lives at tweet.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/ URL. format: Output shape, one of: - "preview" (~1 KB) — rest_id, title, preview_text, cover_image - "plain" (~20 KB, default) — above + plain_text + media URL list + lifecycle_state. The LLM-friendly shape. - "full" (~150 KB+) — raw GraphQL payload including the heavy content_state rich-block tree. Use only when you need it (rich-content rendering, archiving, structure analysis).

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.

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.

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.

Get a Twitter Community by ID.

Args: community_id: The community ID.

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.

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.

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.

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.

Returns JSON with messages (id/text/sender_id/recipient_id/time), next_cursor for pagination via max_id, and when present: timeline_events (non-message entries such as trust_conversation) and warnings (e.g. incomplete history for end-to-end encrypted / X Chat conversations — legacy DM history does not return ciphertext bodies after upgrade).

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.

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.

Get a Twitter List by ID.

Args: list_id: The list ID.

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.

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.

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.

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.

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.

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.

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.

Fetch home timeline tweets.

Args: count: Number of tweets to fetch (default 20).

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).

Fetch a tweet by ID.

Args: tweet_id: The tweet ID (numeric string) or full URL.

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.

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.

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.

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.

Get recent tweets from a specific user.

Args: screen_name: Twitter username (without @). count: Number of tweets to fetch (default 20).

Join a Twitter Community.

Args: community_id: The community ID to join.

Leave a Twitter Community.

Args: community_id: The community ID to leave.

Like a tweet by ID.

Args: tweet_id: The tweet ID.

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 @).

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.

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).

Retweet a tweet by ID.

Args: tweet_id: The tweet ID.

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.

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.

Search tweets.

Args: query: Search query string. count: Number of results (default 20). product: "Latest" or "Top" (default "Latest").

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.

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.

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.

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.

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 @).

Unlike a tweet by ID.

Args: tweet_id: The tweet ID to unlike.

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 @).

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 @).

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).

Read messages from one XChat (encrypted DM) conversation.

Note: returns PRIVATE decrypted message text from your own machine. Reading here does NOT mark the conversation read on X.

Returns JSON messages oldest-first: text, timestamp, direction (incoming/outgoing), sender_screen_name, sequence_number, has_attachment.

Args: conversation_id: From xchat_list_conversations. limit: Max messages, most recent kept (1-500, default 50).

List XChat (encrypted DM) conversations, newest activity first.

Note: returns PRIVATE message previews from your own machine.

Returns JSON conversations: conversation_id, name, screen_name, preview (latest message text; [image attachment]-style placeholder when the message carried no text), timestamp, unread.

Args: limit: Max conversations to return (1-500, default 50). unread_only: Only conversations with unread messages.

Check whether XChat (encrypted DMs) can be read on this machine.

Reads X's locally decrypted store — the browser did the decryption; this only opens the resulting SQLite file read-only. Nothing is sent, marked read, or modified.

Returns JSON with state, and when a store is readable: database_path, conversation_count, last_updated. When no store is configured, returns discovery listing the XChat databases found in local browser profiles so you can pick one.

Configure with XCHAT_BROWSER (auto/chrome/chromium/edge/brave/aside), XCHAT_BROWSER_PROFILE, or XCHAT_DATABASE_PATH.