twittrapi-mcp
OfficialAllows using RapidAPI-hosted TwittrAPI listings as an alternative API backend by configuring a RapidAPI key and optional host, exposing the same Twitter/X data tools and output through RapidAPI.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@twittrapi-mcp show me the latest tweets from @elonmusk"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
twittrapi-mcp – Twitter/X MCP server for Claude, Cursor and other AI agents
An MCP server for TwittrAPI, a REST API for public Twitter/X data: tweets, profiles, followers, search, lists and communities. It lets Claude, Cursor and other MCP clients read that data, from $0.065 per 1,000 calls and with no X developer account.
Get an API key: twittrapi.com/start · Pricing · Docs · Status · also available on RapidAPI
SDKs and integrations: Python · Node.js · Go · n8n · Make · Apify · LangChain · LlamaIndex · Agent skill · Examples
Not affiliated with X Corp.
Hosted server (no install)
Apps that support remote MCP servers can connect by URL instead (available with the hosted release; see twittrapi.com/docs/hosted-mcp):
https://mcp.twittrapi.com/mcpClient | Setup |
Claude.ai / Claude Desktop | Settings > Connectors > Add custom connector, paste the URL, Connect, log in to TwittrAPI and allow access (OAuth) |
ChatGPT | Settings > Apps & Connectors > Advanced settings > Developer mode, then Create with the URL and OAuth |
Claude Code |
|
Cursor |
|
VS Code |
|
With OAuth the app never sees your API key; calls are billed to your balance like any other call. Connected apps are listed (and can be disconnected) in the dashboard under Connected apps.
The hosted server can also post, like, follow and send DMs from your own X account (the account tools), in two ways:
Headers: clients that let you set headers (Claude Code, Cursor, VS Code, scripts) send
X-Twitter-CookieandX-Twitter-Proxy(andX-Twitter-Chat-Passcodefor DMs) with every request. The server uses them for that request only and stores nothing.Dashboard (OAuth): save your X session once under Connected apps in the dashboard, then tick "Act on my X account" when you allow an app. Works in Claude.ai and ChatGPT too.
Guide: twittrapi.com/docs/hosted-mcp#account-tools-post-like-dm.
Related MCP server: XActions MCP Server
What you need
Node.js 20 or newer
A TwittrAPI key, or a RapidAPI key subscribed to the Twitter AIO API
Every tool call is one billed API call on your account.
Install
Claude Code
claude mcp add twittrapi --env TWITTRAPI_API_KEY=your-key -- npx -y twittrapi-mcpClaude Desktop
Open Settings > Developer > Edit Config and add this to claude_desktop_config.json:
{
"mcpServers": {
"twittrapi": {
"command": "npx",
"args": ["-y", "twittrapi-mcp"],
"env": {
"TWITTRAPI_API_KEY": "your-key"
}
}
}
}Restart Claude Desktop afterwards.
Cursor
Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"twittrapi": {
"command": "npx",
"args": ["-y", "twittrapi-mcp"],
"env": {
"TWITTRAPI_API_KEY": "your-key"
}
}
}
}Other clients
Any client that can start a stdio server works. The command is npx -y twittrapi-mcp.
Environment variables
Variable | Required | Description |
| one of the two keys | Your TwittrAPI key. Sent as the |
| one of the two keys | RapidAPI key. Used only when |
| no | Host of your RapidAPI listing. Default |
| no | API base URL for the direct API. Default |
| no |
|
| no | Cookie of your own logged-in x.com session. Turns on the account tools together with |
| no | Your proxy for the account tools, |
| no | Your X Chat passcode. Adds |
If neither key is set, the server still starts and lists its tools, but every call returns an error explaining how to set a key.
Using RapidAPI instead
If you bought access through RapidAPI, set RAPIDAPI_KEY instead of TWITTRAPI_API_KEY:
"env": { "RAPIDAPI_KEY": "your-rapidapi-key" }Requests then go to https://twitter-aio.p.rapidapi.com with the x-rapidapi-key and
x-rapidapi-host headers. The tools and their output are the same.
Subscribed to another TwittrAPI listing on RapidAPI? Set its host:
"RAPIDAPI_HOST": "twttr.p.rapidapi.com".
Tools
These tools read public data and are always available. The account tools are added when you configure your X session.
Tool | What it does |
| Profile by handle, including the numeric user ID |
| Profile by numeric user ID |
| Resolve a handle to its user ID |
| Profiles for up to 500 user IDs at once |
| A user's tweets |
| A user's tweets and replies |
| A user's tweets with photos or videos |
| A user's followers |
| Accounts a user follows |
| A user's verified followers |
| Accounts affiliated with an organization |
| Whether one account follows up to 50 others, and back |
| "About this account" for up to 20 handles |
| Search with X operators; Top, Latest, People, Photos or Videos |
| A tweet and its reply thread |
| Up to 100 tweets by ID at once |
| Users who retweeted a tweet |
| Tweets quoting a tweet |
| Only the replies to a tweet |
| The author's own thread around a tweet |
| List name, owner and counts |
| Tweets from a list's members |
| Members of a list |
| Community details |
| A community's About page: rules, moderators, members |
| Tweets in a community |
| Find communities by keyword |
| Trending topics for a location (WOEID) |
| Locations that have trends, with their WOEIDs |
| An X Space: title, state, host and participants |
The user timeline tools (get_user_tweets, get_followers and so on) accept either userId or
username. The batch tools are billed one call per handle; tweets_by_ids is one call however
many IDs.
Account tools
With TWITTRAPI_X_COOKIE and TWITTRAPI_X_PROXY set, the server also lists tools that act on
your own X account:
Tool | What it does |
| Post a tweet; optional quote ( |
| Reply to a tweet |
| Delete one of your tweets |
| Like or unlike a tweet |
| Retweet or undo a retweet |
| Add or remove a bookmark |
| Follow or unfollow (by |
| Your DM inbox |
| Send a direct message (needs |
| Pending message requests; does not accept them or mark them as seen |
| Accept a one-to-one request and send the first reply (needs |
| Delete a request from your inbox; the sender is not told (needs |
| Create a list |
| Add or remove a list member |
| Save a draft, list your drafts |
| Your bookmark folders and the tweets in one (X Premium) |
| Search your bookmarks |
| Communities you are a member of |
| Your X Articles, drafts or published, and one article (X Premium) |
| Save a new article as a draft, change one (X Premium) |
| Publish, unpublish or delete an article (X Premium) |
How to get the cookie and set up a proxy: twittrapi.com/docs/x-session.
The cookie needs auth_token and ct0; direct messages also need twid.
"env": {
"TWITTRAPI_API_KEY": "your-key",
"TWITTRAPI_X_COOKIE": "auth_token=...; ct0=...; twid=u%3D...",
"TWITTRAPI_X_PROXY": "http://user:pass@host:port"
}The cookie and proxy stay in the server's configuration. They are not tool arguments, so the model never sees them, and they are never logged or returned in a result.
Write tools are marked
readOnlyHint: false(deletions and undo actions alsodestructiveHint: true), so clients ask before running them.Each call is one billed API call, like the read tools.
Over HTTP (your own instance or the hosted server) the session comes with the request: the
X-Twitter-Cookie,X-Twitter-ProxyandX-Twitter-Chat-Passcodeheaders, or, on the hosted server, the session saved in the dashboard for an OAuth grant with thex:writescope. See HTTP mode.
Response format
Tool results use the API's simple format by default:
flat camelCase JSON with a fixed schema ({"data": [...], "nextCursor": ..., "hasNextPage": ...}
for lists, {"data": {...}} for single objects). Tweets carry id, url, text, createdAt,
author, counts, media, quoted, retweetOf and a few more fields; users carry username,
name, description, counts and so on. That is about 60 % fewer tokens than X's raw GraphQL JSON.
To get the raw JSON instead (for cards, polls, edit history, community notes and other fields the simple format leaves out):
per call: the tools take an optional
formatargument,"simple"or"raw";for the whole server: set
TWITTRAPI_RESPONSE_FORMAT=raw(theformatargument still wins).
A few endpoints have no simple format: get_space, get_community_about, the batch tools and the
newer account tools (bookmark folders and search, communities, articles). These tools have no
format argument and always return raw JSON.
Output size and pagination
Raw responses can be several hundred KB. Every tool takes an optional max_chars argument
(default 50,000, range 1,000 to 1,000,000). Longer output is cut and ends with a
[TRUNCATED ...] marker.
Paginated tools print the cursor above the JSON, so truncation never removes it:
next_cursor: DAABCgABGZ...
Pass next_cursor as `cursor` to get the next page.
{"data":{...}}On the last page the header reads next_cursor: none (last page, no more results). In the simple
format that is when hasNextPage is false. In the raw format it happens when the response has no
next cursor (empty likes timelines included), when X returns the cursor you just sent, or
when a page holds only cursors and no results.
Errors
API errors come back as tool errors with a short explanation, for example:
402: the account has no balance left
429: rate limit hit, wait before retrying
404: the user or tweet does not exist, is private or is suspended
5xx: temporary upstream problem
HTTP mode (remote hosting)
npx -y twittrapi-mcp --http --port 3333 --host 0.0.0.0This serves a stateless Streamable HTTP
endpoint at /mcp and a health check at /health. The default host is 127.0.0.1. Every POST
gets its own server instance bound to the caller's credentials, so any number of instances can
run behind a load balancer without sticky sessions. GET /mcp answers 405 (no server-initiated
stream); the legacy SSE transport is not offered.
In HTTP mode the server does not use a key from its own environment. Each request carries the caller's credentials:
X-API-KEY: <key>orAuthorization: Bearer <key>for the direct APIx-rapidapi-key: <key>for RapidAPI, plusx-rapidapi-host: <host>for a listing other thantwitter-aio.p.rapidapi.com(must end in.p.rapidapi.com)Authorization: Bearer twa_at_...: a TwittrAPI OAuth access token (hosted mode, below)
The account tools appear when the request also carries the caller's X session:
X-Twitter-Cookie: auth_token=...; ct0=...; twid=u%3D...andX-Twitter-Proxy: http://user:pass@host:port(both or neither;400otherwise), plusX-Twitter-Chat-Passcodefor the DM tools. The values are used for that request only, never stored, logged or returned.In hosted mode, an OAuth token with the
x:writescope: the dashboard sends the X accounts the customer saved there. Headers take precedence over them. With more than one saved account, every account tool takes an optionalaccountargument (@handleor numeric user ID; the default account when it is left out), the server instructions name the accounts, and the freelist_x_accountstool lists them.
TWITTRAPI_X_COOKIE and TWITTRAPI_X_PROXY from the server's own environment are ignored in HTTP
mode, so one deployment never acts for everyone with one account. TWITTRAPI_BASE_URL and TWITTRAPI_RESPONSE_FORMAT are still read from the environment; callers
can pick the format per call with the format argument. Put the server behind HTTPS if it is
reachable from the internet.
Example client config for your own instance (Claude Code):
claude mcp add --transport http twittrapi https://your-host.example.com/mcp --header "X-API-KEY: your-key"Hosted mode with OAuth
For clients that require OAuth (Claude.ai connectors, ChatGPT), the server acts as an OAuth 2.1 resource server and the TwittrAPI dashboard as the authorization server (dynamic client registration, PKCE S256, consent screen, rotating refresh tokens). The server:
answers requests without credentials with
401andWWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="mcp";serves RFC 9728 metadata at
/.well-known/oauth-protected-resource/mcpand/.well-known/oauth-protected-resource, and relays the dashboard's RFC 8414 metadata at/.well-known/oauth-authorization-server;checks each access token with the dashboard's internal introspection endpoint (shared secret), caches valid results for up to
OAUTH_CACHE_SECONDS(30) and invalid ones for 5 s, and accepts only tokens whose audience isMCP_PUBLIC_URL;calls the API with the key of the account behind the token. The key never reaches the client.
registers the account tools only for tokens with the
x:writescope, which the customer grants with a separate checkbox on the consent screen and only after saving an X session in the dashboard. Deleting the saved session removes the tools withinOAUTH_CACHE_SECONDS. Invalid or revoked tokens get401witherror="invalid_token"; if the dashboard cannot be reached the answer is503withRetry-After, so clients keep their tokens.
Environment (HTTP mode)
Variable | Default | Description |
|
| Listen address (the Docker image uses |
|
| Gateway the tools call |
|
| Default format of tool results |
| – | Public URL of |
| – | Authorization server, e.g. |
| – | Shared secret with the dashboard (32+ characters). OAuth is on when these three are set. |
|
| Internal URL of the introspection endpoint |
|
| Where the relayed metadata is fetched |
|
| Cache for valid tokens (max 300). Revocations take effect within this time. |
|
| Requests in flight per key and instance; more get |
| – | Optional. Usage events, one per tool call, POSTed in batches to this URL (the TwittrAPI dashboard: |
|
| Bearer secret for |
|
| Larger request bodies get |
|
| Requests running longer get |
| – | Comma-separated |
| – |
|
|
|
|
Logs are JSON lines on stdout, one per request: request id, client IP, auth kind
(api_key, rapidapi, oauth, none), a hashed key id (k_ + 12 hex characters), OAuth client
and account id, JSON-RPC method, tool name, status and duration. Keys and tokens are never logged.
Docker / Coolify
docker build -t twittrapi-mcp .
docker run -p 3000:3000 -e MCP_PUBLIC_URL=... -e OAUTH_ISSUER=... -e OAUTH_INTROSPECTION_SECRET=... twittrapi-mcpIn Coolify: build pack Dockerfile, port 3000, health check path /health, domain
mcp.twittrapi.com, and the variables above. Set OAUTH_INTROSPECTION_URL to the dashboard's
internal address when both run on the same server.
Development
npm install
npm run build
npm testnpm test builds first, then runs unit tests, a protocol test that starts the server over stdio
and HTTP against a local mock API, and tests of hosted mode (OAuth challenge and metadata, token
introspection and caching, audience check, limits, log redaction) against a fake dashboard.
To add or change a tool, edit src/endpoints.ts. Each entry has a name, description, API path and
zod parameter schemas. Every tool also gets max_chars, and format unless the entry sets rawOnly.
An entry can set a simplify function to reshape the parsed JSON further; none do. Account tools live in src/actions.ts.
Try the server interactively with the MCP Inspector:
npx @modelcontextprotocol/inspector -e TWITTRAPI_API_KEY=your-key node dist/index.jsSupport
Questions, bugs or a higher rate limit: email support@twittrapi.com or open an issue in this repository. Service status: twittrapi.com/status. News and changes: the TwittrAPI Telegram channel (link on the website).
License
MIT
Available Tools
30 toolsget_communityGet communityBRead-onlyIdempotentInspect
Get an X Community's name, description, rules, member count and admins.
Inputs: communityId (required), format, max_chars.
get_community_aboutGet community about pageARead-onlyIdempotentInspect
Get the About page of an X Community: description, rules, creation date, moderators and a preview of members. Returns raw JSON.
Inputs: communityId (required), max_chars.
get_community_tweetsGet community tweetsBRead-onlyIdempotentInspect
Get tweets posted in an X Community. Paginated.
Inputs: communityId (required), count, cursor, format, +1 more.
get_followersGet followersARead-onlyIdempotentInspect
Get accounts that follow a user, newest followers first. Paginated.
Inputs: count, cursor, format, userId, +2 more.
get_followingGet followingCRead-onlyIdempotentInspect
Get accounts a user follows. Paginated.
Inputs: count, cursor, format, userId, +2 more.
get_friendships_batchGet relationships with many accountsARead-onlyIdempotentInspect
Check whether one account follows up to 50 others, and whether they follow it back, in one call. Returns raw JSON: one relationship per target, in order, plus errors for handles that could not be looked up.
Inputs: sourceUsername (required), targetUsernames (required), max_chars.
get_list_detailsGet list detailsARead-onlyIdempotentInspect
Get an X list's name, description, owner, and member/follower counts.
Inputs: listId (required), format, max_chars.
get_list_membersGet list membersBRead-onlyIdempotentInspect
Get the accounts that are members of an X list. Paginated.
Inputs: listId (required), count, cursor, format, +1 more.
get_list_tweetsGet list tweetsARead-onlyIdempotentInspect
Get the tweet timeline of an X list (tweets from its members), newest first. Paginated.
Inputs: listId (required), count, cursor, format, +1 more.
get_spaceGet SpaceARead-onlyIdempotentInspect
Get an X Space by ID: title, state, host and participants, and whether a replay is available. Returns raw JSON.
Inputs: spaceId (required), max_chars.
get_trend_locationsGet trend locationsARead-onlyIdempotentInspect
List the locations (countries and cities) that have trends, with their WOEIDs for get_trends.
Inputs: format, max_chars.
get_trendsGet trendsARead-onlyIdempotentInspect
Get trending topics for a location by WOEID (1 = worldwide, 23424977 = United States, 23424975 = United Kingdom). Use get_trend_locations to look up other WOEIDs.
Inputs: locationId (required), format, max_chars.
get_tweetGet tweetARead-onlyIdempotentInspect
Get a tweet by ID with full text, author, media, engagement counts and the reply thread (conversation). Use cursor to load more replies.
Inputs: tweetId (required), cursor, format, max_chars, +1 more.
get_tweet_quotesGet tweet quotesARead-onlyIdempotentInspect
Get tweets that quote a given tweet. Paginated.
Inputs: tweetId (required), count, cursor, format, +1 more.
get_tweet_repliesGet tweet repliesARead-onlyIdempotentInspect
Get only the replies to a tweet, without the tweet itself or the tweets above it. Paginated.
Inputs: tweetId (required), cursor, format, max_chars, +2 more.
get_tweet_retweetsGet tweet retweetersBRead-onlyIdempotentInspect
Get the users who retweeted a tweet. Paginated.
Inputs: tweetId (required), count, cursor, format, +1 more.
get_tweet_threadGet tweet threadARead-onlyIdempotentInspect
Get the author's own thread around a tweet in reading order: their tweets above it and their replies to themselves below it, up to the first reply by someone else.
Inputs: tweetId (required), format, max_chars.
get_user_about_batchGet "About this account" for many usersARead-onlyIdempotentInspect
Get the "About this account" data (country the account is based in, username changes, verification) of up to 20 accounts in one call. Returns raw JSON: one entry per handle, in order, plus errors for handles that could not be looked up.
Inputs: usernames (required), max_chars.
get_user_affiliatesGet affiliatesBRead-onlyIdempotentInspect
Get the accounts affiliated with an organization, as in the Affiliates tab of its profile. Empty for accounts without affiliates. Paginated.
Inputs: count, cursor, format, userId, +2 more.
get_user_by_idGet user by IDARead-onlyIdempotentInspect
Get an X user's profile by numeric user ID (rest_id). Same data as get_user_by_username.
Inputs: userId (required), format, max_chars.
get_user_by_usernameGet user by usernameARead-onlyIdempotentInspect
Get an X (Twitter) user's profile by handle: name, bio, follower/following counts, verification, created date, and the numeric user ID (rest_id) needed by other tools.
Inputs: username (required), format, max_chars.
get_user_mediaGet user mediaARead-onlyIdempotentInspect
Get a user's tweets that contain photos or videos. Paginated.
Inputs: count, cursor, format, userId, +2 more.
get_user_tweetsGet user tweetsARead-onlyIdempotentInspect
Get a user's recent tweets (their profile timeline, without replies), newest first, including retweets and pinned tweet. Paginated.
Inputs: count, cursor, format, userId, +2 more.
get_user_tweets_and_repliesGet user tweets and repliesBRead-onlyIdempotentInspect
Get a user's tweets including their replies to others, newest first. Paginated.
Inputs: count, cursor, format, userId, +2 more.
get_verified_followersGet verified followersBRead-onlyIdempotentInspect
Get a user's followers that have a verified (blue check) badge. Paginated.
Inputs: count, cursor, format, userId, +2 more.
search_communitiesSearch communitiesARead-onlyIdempotentInspect
Search X Communities by keyword. Returns community IDs for get_community and get_community_tweets. Paginated.
Inputs: searchTerm (required), count, cursor, format, +1 more.
search_tweetsSearch tweetsARead-onlyIdempotentInspect
Search X like the search box. Supports X search operators in the query, e.g. from:user, to:user, "exact phrase", lang:en, since:2025-01-01, until:2025-02-01, min_faves:100, filter:media, -filter:replies. category Latest gives newest first; People returns accounts instead of tweets. Paginated.
Inputs: searchItem (required), count, cursor, format, +2 more.
tweets_by_idsGet tweets by IDsARead-onlyIdempotentInspect
Get up to 100 tweets in one call by numeric tweet ID, billed as one call. Results keep the request order; tweets that were deleted or never existed are left out (raw format: an empty {} in their place).
Inputs: ids (required), format, max_chars.
username_to_idUsername to user IDARead-onlyIdempotentInspect
Resolve an X handle to its numeric user ID. Cheaper and smaller than get_user_by_username when you only need the ID.
Inputs: username (required), format, max_chars.
users_by_idsGet users by IDsARead-onlyIdempotentInspect
Get profiles for up to 500 X users in one call, by numeric user ID.
Inputs: ids (required), format, max_chars.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools map to distinct resources or actions, and the descriptions make differences clear. There is some overlap between get_user_by_id/get_user_by_username/username_to_id and between get_community/get_community_about, but the intended use cases are mostly distinguishable.
The set is predominantly consistent snake_case with predictable verb_noun naming such as get_user_tweets and search_tweets. Minor deviations like username_to_id, users_by_ids, and tweets_by_ids are still readable and do not seriously undermine consistency.
Thirty tools is heavy for a single MCP surface, even for a broad Twitter/X data domain. Several batch, raw-JSON, and specialized variants could likely be consolidated or made optional to reduce cognitive load.
The server covers a strong read-only slice of the X API: users, tweets, social graph, lists, communities, trends, and Spaces. Some adjacent read endpoints such as likes, bookmarks, and broader list/Space detail are missing, but core workflows are covered.
Maintenance
Related MCP Connectors
Hosted MCP server from TwitterAPI.io that gives AI agents read-only access to Twitter/X data. 12 tools: tweet search with X operators, user profiles, a user's latest tweets, followers and followings, replies, quotes, retweeters, mentions and trends. Connect at https://mcp.twitterapi.io/mcp with a TwitterAPI.io API key or account sign-in; usage is paid per result returned.
Twitter (X) data for agents: profiles, tweets, search, followers, lists. $0.0006 per call.
X (formerly Twitter) posts, profiles, and search for AI agents. Free key, self-minted, no signup.
Twitter (X) API alternative for AI agents: tweet search, profiles, followers. $0.0002 per result.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables LLM agents to interact with Twitter (X) for searching tweets, posting content with images, analyzing engagement, and extracting topics using the Twitter API.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to automate Twitter/X interactions with over 140 tools, requiring no API key.440 npm656Apache 2.0
- AlicenseCqualityBmaintenanceEnables AI agents to search, read user profiles, timelines, media, follow threads, track trends, and manage accounts on X/Twitter via GraphQL, without browser automation or paid API keys.113721 PyPI12MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to fully automate X/Twitter interactions including searching, posting, engaging, and managing multiple accounts without paid API keys.MIT