Getting Started
Twitter MCP Server | Twitter Tools for AI Agents
Connect the @twitterapis/mcp server to Claude, Cursor, and any Model Context Protocol client so your AI agent can search tweets and read profiles as native tools.
The official Model Context Protocol server, @twitterapis/mcp, exposes the API as native tools for Claude, Cursor, and any MCP client. Ask your agent to "find the latest tweets about AI agents" or "pull @openai's followers" and it calls the API directly, no glue code.
Every tool maps to a REST endpoint at https://api.twitterapis.com. The server holds no state and forwards your API key on each call.
No install step
The server runs on demand with npx. You only need an API key. New accounts start with $0.50 in free credits, enough for hundreds of calls, no card required. Grab one from the dashboard.
Connect a client
Add the server block to your client's MCP config, set TWITTERAPIS_KEY, and restart the client. The twitter_* tools then appear in the tool list.
Open Settings, then Developer, then Edit Config, and add the server to claude_desktop_config.json:
{
"mcpServers": {
"twitterapis": {
"command": "npx",
"args": ["-y", "@twitterapis/mcp@latest"],
"env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
}
}
}Edit ~/.cursor/mcp.json (or Settings, then MCP, then Add) and add:
{
"mcpServers": {
"twitterapis": {
"command": "npx",
"args": ["-y", "@twitterapis/mcp@latest"],
"env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
}
}
}Any client that speaks the Model Context Protocol over stdio can launch the server the same way. The command is npx -y @twitterapis/mcp@latest with TWITTERAPIS_KEY set in the environment:
{
"command": "npx",
"args": ["-y", "@twitterapis/mcp@latest"],
"env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
}Configuration
| Env var | Required | Default | Purpose |
|---|---|---|---|
TWITTERAPIS_KEY | Yes | none | Your API key from the dashboard. |
TWITTERAPIS_BASE_URL | No | https://api.twitterapis.com | Override the API host. |
TWITTERAPIS_TIMEOUT_MS | No | 30000 | Per-request timeout in milliseconds. |
Tools
The server exposes 113 tools: 69 read and 44 write, as published in @twitterapis/mcp@0.24.1. Read tools need only your API key. Tools that act on an X account, and private-timeline reads, also need a registered session (pass auth_token and ct0). User tools accept a username or a numeric user_id; tweet tools accept a tweet id; paged tools take a cursor.
Read tools (69)
| Tool | What it does |
|---|---|
twitter_advanced_search | Searches recent tweets with X's advanced-search operators: from:, to:, since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N, min_retweets:N, filter:links, -filter:replies... |
twitter_user_search | Searches Twitter/X user accounts by display name or handle (X's People search). |
twitter_user_info | Returns a user's complete public profile by @handle: display name, bio, follower count, following count, verification status, location, website, account creation... |
twitter_user_info_by_id | Returns a user's complete public profile by numeric user id: display name, bio, follower and following counts, verification status, location, website, account... |
twitter_user_status | Reports whether a Twitter/X account is alive, suspended, or deleted. |
twitter_user_about | Returns a user's full 'About' object: the structured profile facts X surfaces beyond the bio, including account category and professional/business labels... |
twitter_user_about_batch | Returns the 'About' object (account country, how the account was created, username-change history, verification and the other About fields) for up to 100 accounts... |
twitter_user_affiliates | Lists the affiliated accounts of an organization profile (the smaller accounts X displays under a company's 'Affiliated' badge, e.g. |
twitter_check_follow_relationship | Returns the follow relationship between two accounts: whether the source follows the target, whether the target follows the source, and blocking/muting flags... |
twitter_check_follow_relationship_batch | Checks one account against up to 100 others in one call. |
twitter_audience_summary | Summarises an audience in one call: samples up to 100 followers of an account (username or user_id) or retweeters of a tweet (tweet_id), reads each sampled account's... |
twitter_user_tweets | Returns a user's recent posting timeline, cursor-paginated further back. |
twitter_user_tweets_and_replies | Returns a user's full activity timeline: their original tweets and their replies to others, cursor-paginated. |
twitter_user_tweets_complete | Returns a large batch of a user's tweet history in one call, auto-paginating server-side across upstream pages: { count, next_cursor, has_more, tweets }. |
twitter_user_media | Returns the images and videos a user has posted: media-containing tweets with URLs to the media files, dimensions, and type (photo/video/animated_gif), cursor-paginated. |
twitter_user_mentions | Returns recent public tweets that mention (@ tag) a user, found with the to: search operator, with author info and metrics, cursor-paginated. |
twitter_user_likes | Returns the tweets a user has liked (their public Likes tab), most recent first, each with author and metrics, plus a pagination cursor. |
twitter_user_followers | Lists the accounts that follow a given user, with profile data for each follower (username, display name, bio, follower count), cursor-paginated for large audiences. |
twitter_user_following | Lists the accounts a given user follows, with profile data for each account followed, cursor-paginated. |
twitter_user_followers_v2 | Lists a user's followers in the v2 response shape: richer profile fields and more reliable cursoring for deep follower lists. |
twitter_user_following_v2 | Lists the accounts a user follows in the v2 response shape: richer profile fields and more reliable cursoring for deep following lists. |
twitter_user_verified_followers | Lists a user's followers that have a verified account (checkmark), cursor-paginated: the follower list filtered to verified accounts, which surfaces notable... |
twitter_followers_you_know | Lists the 'Followers you know' for a target user id: the followers of that account that the authenticated account also follows (mutual-connection overlap). |
twitter_tweet_detail | Returns the full detail of a single tweet: text, author profile, post timestamp, like/retweet/reply/quote counts (quote_count is X's own total of quote tweets)... |
twitter_tweet_replies | Returns replies to a specific tweet, each with author, text and metrics, cursor-paginated. |
twitter_tweet_replies_complete | Returns every direct reply under a tweet in one call, walking the reply pages server-side: { count, next_cursor, has_more, is_complete, pages_fetched, sort, tweets }. |
twitter_tweet_thread | Returns all tweets in a thread: the connected chain of tweets posted by the SAME author in sequence (a tweetstorm or numbered thread). |
twitter_tweet_retweeters | Lists the accounts that retweeted a specific tweet, with profile data for each retweeter, cursor-paginated. |
twitter_tweet_quotes | Lists the tweets that QUOTE a specific tweet, cursor-paginated as full tweet objects, so each carries the commentary attached rather than just a number. |
twitter_list_members | Lists the members of a Twitter/X List by its numeric list id, with profile data for each member, cursor-paginated. |
twitter_list_followers | Lists a public List's followers by its numeric id, cursor-paginated. |
twitter_list_tweets | Returns the posts written by the members of a public Twitter/X List, newest first, through X's search index. |
twitter_list_timeline | Returns a public Twitter/X List's NATIVE feed: the same posts and the same ordering the List shows on x.com, including members' retweets. |
twitter_spaces_info | Get metadata and the participant roster for one X Space by id, live or ended: title, lifecycle state (Scheduled, NotStarted, Running or Ended), host, topics... |
twitter_community_search | Finds X Communities by keyword, cursor-paginated, returning each community's id. |
twitter_community_info | Returns the metadata for one X Community by its numeric id: name, description, member_count, moderator_count, join_policy, invites_policy, the join question, primary... |
twitter_community_about | The About tab for one X Community: its moderators, and a preview of its members, both returned as FULL user profiles with bio, follower and following counts, tweet... |
twitter_community_members | Lists the member roster of an X Community, cursor-paginated, with each row carrying that member's own role in the community: 'Admin', 'Moderator' or 'Member'. |
twitter_community_moderators | Lists the moderators and admins of an X Community, cursor-paginated, in { user, role } rows (the array is named members). |
twitter_community_tweets | Returns an X Community's own post timeline, cursor-paginated as full tweet objects, with the community's PINNED post in its own separate 'pinned' field rather than as... |
twitter_community_memberships | The INVERSE community lookup: given a numeric X USER id, lists the communities that account belongs to, cursor-paginated. |
twitter_grok_config | Reports whether the authenticated account can use Grok, and which models it may pick: eligibility, X's own reasons when it is NOT eligible (passed through verbatim... |
twitter_trends | Returns the current top trends for a location, or for one of X's Explore topic tabs. |
twitter_trends_locations | Lists every location X publishes trends for, each with its name and numeric WOEID. |
twitter_account_me | Returns your twitterapis.com account details: email, name, credits remaining, credits used, total requests made, and account creation date. |
twitter_account_payments | Returns your twitterapis.com payment history: the list of top-ups and charges on the account. |
twitter_feedback_get | Returns the status of a feedback report this account sent earlier, by its server id: status new, triaged, shipped or declined, the team's response text if any... |
twitter_feedback_list | Lists the feedback reports this account has already SENT to twitterapis.com, newest first: server-side reports, not local drafts that are still unsent. |
twitter_home_timeline | Returns the authenticated account's Home timeline (the 'Following'/'For you' feed), most recent first: what that account sees when it opens X. |
twitter_bookmarks | Lists the authenticated account's bookmarked tweets, most recent first. |
twitter_blocking | Lists the accounts the authenticated account has BLOCKED, as full user objects, cursor-paginated. |
twitter_muting | Lists the accounts the authenticated account has MUTED, as full user objects, cursor-paginated. |
twitter_bookmark_search | Full-text search within the authenticated account's bookmarks. |
twitter_bookmark_folders | Lists the authenticated account's bookmark FOLDERS (X's internal name: collections), the named groups saved tweets can be organised into, separate from the flat... |
twitter_bookmark_folder_timeline | Returns the tweets inside ONE of the authenticated account's bookmark folders, identified by folder_id. |
twitter_dm_list | Lists the authenticated account's Direct Message conversations (inbox), each with the participant and its conversation_id. |
twitter_dm_conversation | Returns the messages in one Direct Message conversation by its conversation_id. |
twitter_draft_list | Lists the PRIVATE drafts saved on the authenticated account, the source of draft ids for an edit or a delete. |
twitter_scheduled_list | Lists the posts QUEUED to publish on the authenticated account: the source of scheduled ids for a cancel, and a record of what is already queued. |
twitter_customer_session_status | Reads back the X account session registered against this API key, without changing it. |
twitter_media_status | Reports whether an uploaded media_id has finished processing on X. |
twitter_article_get | Returns an article's full content (title, content_state, cover media, author, timestamps, public_url). |
twitter_article_list | Lists the authenticated account's own articles (drafts or published), most recent first. |
twitter_monitor_list | List every monitor on your account: id, subject (its from:<handle> query), kind, status ('active' or 'paused'), degraded flag, events_possibly_missed, webhook_ids... |
twitter_monitor_health | Returns one monitor's current status, degradation flag, poll interval, possibly-missed-event count, and cursor position (last_tweet_id, last_poll_at), for a health... |
twitter_monitor_account_health | Account-wide monitoring rollup in ONE call, with no monitor id: service status ('operational' or 'degraded'), active/paused/total counts across every monitor... |
twitter_monitor_deliveries | Lists the most recent monitor delivery events across every monitor, most recent first: id, monitor_id, tweet_id, status, tweet_created_at, and the real measured... |
twitter_x_user_stream_list_users | Compatibility endpoint with an x_user_stream-shaped envelope: lists every account currently tweet-monitored. |
twitter_monitor_webhook_list | Lists every webhook registered on the account: id, url, status ('active' delivers, 'disabled' means the endpoint returned a 410 Gone and needs re-registering... |
Write tools (44)
Write tools change state: they post, delete, like, follow, message, edit a profile, or create and manage monitors and webhooks. Tools that act on an X account need a registered session; monitor, webhook and feedback tools need only your API key. Prices differ by tool, so read the price on each endpoint's reference page.
| Tool | What it does |
|---|---|
twitter_grok_chat | Asks X's own Grok a question as the authenticated account and returns ONE complete JSON reply: the answer text, citations (url, domain, title, snippet) merged... |
twitter_feedback_send | Reports a product problem or gap in twitterapis.com to its team from inside this session. |
twitter_dm_send | Sends a Direct Message as the authenticated account to a recipient's numeric user id (recipient_id) with the message text. |
twitter_create_tweet | Posts a new tweet as the authenticated account. |
twitter_delete_tweet | Deletes a tweet as the authenticated account. |
twitter_update_profile | Changes the display name, bio, location or link on the authenticated account's own X profile. |
twitter_update_avatar | Replaces the profile picture on the authenticated account's own X profile. |
twitter_update_banner | Replaces the wide header image on the authenticated account's own X profile. |
twitter_draft_create | Saves a PRIVATE draft tweet on the authenticated account. |
twitter_draft_edit | Replaces the contents of one existing PRIVATE draft on the authenticated account. |
twitter_draft_delete | Deletes one PRIVATE draft from the authenticated account by id. |
twitter_scheduled_create | Schedules a tweet to POST PUBLICLY at a future instant from the authenticated account. |
twitter_scheduled_delete | Cancels one PENDING scheduled post on the authenticated account so it does not publish. |
twitter_favorite_tweet | Likes (favorites) a tweet as the authenticated account. |
twitter_unfavorite_tweet | Removes a like (unfavorite) from a tweet as the authenticated account. |
twitter_retweet | Retweets a tweet as the authenticated account. |
twitter_unretweet | Undoes a retweet as the authenticated account. |
twitter_bookmark_tweet | Bookmarks a tweet to the authenticated account's private bookmarks. |
twitter_unbookmark_tweet | Removes a tweet from the authenticated account's bookmarks. |
twitter_follow_user | Follows a user as the authenticated account, by numeric user_id or by @handle (exactly one of the two). |
twitter_unfollow_user | Unfollows a user as the authenticated account, by numeric user_id or by @handle (exactly one of the two). |
twitter_list_add_member | Adds one account to a Twitter/X List that the registered X session owns, by numeric list id and numeric user id. |
twitter_list_remove_member | Removes one account from a Twitter/X List that the registered X session owns, by numeric list id and numeric user id. |
twitter_list_create | Creates a new Twitter/X List owned by the registered X session, with a name and an optional description and privacy flag. |
twitter_customer_session | Registers your own X account session against the API key, so the authenticated-account reads (home timeline, bookmarks, DMs, likes, articles) and the write actions... |
twitter_customer_session_delete | Revokes the X account session registered against this API key, deleting the stored auth_token and ct0 from twitterapis.com. |
twitter_user_login | Logs in to X with a username and password (plus totp_secret if the account has 2FA) and stores the resulting session against the API key, so the authenticated-account... |
twitter_media_upload | Uploads an image to X and returns a media_id for a tweet's media_ids. |
twitter_article_create | Starts a new DRAFT article ('Note') as the authenticated account. |
twitter_article_update_cover_media | Attaches an ALREADY-UPLOADED image as the cover of a DRAFT or PUBLISHED article, as the authenticated account. |
twitter_article_update_title | Sets or replaces the title of a DRAFT or PUBLISHED article as the authenticated account. |
twitter_article_update_content | Replaces the body content of a DRAFT or PUBLISHED article as the authenticated account. |
twitter_article_publish | Publishes a DRAFT article as the authenticated account, transitioning it to Published and posting a REAL, PUBLIC announcement tweet that followers and anyone... |
twitter_article_unpublish | Reverts a PUBLISHED article back to Draft as the authenticated account. |
twitter_article_delete | Deletes an article as the authenticated account. |
twitter_monitor_create | Starts watching an X account for new posts. |
twitter_monitor_update | Partially updates an existing monitor: pause or resume it via status, change which webhooks receive its events via webhook_ids, change or clear its domain_filter... |
twitter_monitor_delete | Stops and removes a monitor by id. |
twitter_x_user_stream_add_user | Compatibility endpoint with an x_user_stream-shaped request/response envelope: watches an X account for new posts, translated onto the same underlying monitor system. |
twitter_x_user_stream_remove_user | Compatibility endpoint with an x_user_stream-shaped envelope: stops watching an account. |
twitter_monitor_webhook_create | Registers an HTTPS endpoint to receive signed monitor events. |
twitter_monitor_webhook_delete | Soft-deletes a webhook by id: it stops receiving deliveries immediately and disappears from the webhook list, but delivery history referencing it is retained rather... |
twitter_monitor_webhook_test | Sends one HMAC-signed test event to this webhook's URL right now and returns the outcome synchronously: delivered (true if the endpoint returned a 2xx within... |
twitter_monitor_webhook_redrive | Replays deliveries that dead-lettered while the endpoint was down. |
Billing
Most MCP calls bill at $0.0008 per call, the same as a direct REST call. Some cost more, for example twitter_tweet_thread at $0.004, twitter_user_tweets_complete and twitter_tweet_replies_complete at $0.0024, and tweet creation, DM send and the DM reads (twitter_dm_list, twitter_dm_conversation) at $0.0016. The account, monitor, webhook and feedback tools are free, except the credential login at $0.01, charged only when it succeeds. Your first $0.50 is free. See Rate limits for the full pay-per-call model.
Prefer raw HTTP?
You do not need the MCP server to use the API. Every tool here is a thin wrapper over a REST endpoint you can call yourself.
Quickstart
Make your first REST request in under two minutes.
Client libraries
Copy-paste typed clients for JavaScript and Python.
Advanced Tweet Search
The flagship endpoint behind twitter_advanced_search.
Authentication
How the bearer token works and where to find your key.
FAQ
Which clients does the MCP server support?
Claude Desktop, Cursor, and any client that speaks the Model Context Protocol over stdio. Add the server block and set TWITTERAPIS_KEY.
Do I need to install anything?
No. The server runs on demand with npx -y @twitterapis/mcp@latest. You only need an API key, with $0.50 in free credits to start.
Are the MCP tools read-only?
No. The server exposes 113 tools, 69 read and 44 write. Write tools post, delete, like, retweet, bookmark, follow, message and manage monitors; the ones that act on an X account need a registered session. Most calls bill at $0.0008, the same as a read, some cost more and some are free; each endpoint's reference page states its price.
Was this page helpful?
Write Sessions
Register your own X session once, or pass credentials per request. Covers proxy_url egress routing and exactly what is stored.
Client Libraries
Copy-paste minimal TwitterAPIs clients for JavaScript and Python, built on the bearer-token pattern, with retries and cursor pagination handled for you.