
MCP server for TwittrAPI: read public Twitter/X tweets, profiles, followers and search results. Pay
MCP server for TwittrAPI: read public Twitter/X tweets, profiles, followers and search results. Pay as you go from $0.065 per 1,000 calls.
·
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.
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/mcp| Client | 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 | claude mcp add --transport http twittrapi https://mcp.twittrapi.com/mcp (OAuth), or add --header "Authorization: Bearer $TWITTRAPI_API_KEY" |
| Cursor | {"mcpServers": {"twittrapi": {"url": "https://mcp.twittrapi.com/mcp", "headers": {"X-API-KEY": "${env:TWITTRAPI_API_KEY}"}}}} in mcp.json |
| VS Code | {"servers": {"twittrapi": {"type": "http", "url": "https://mcp.twittrapi.com/mcp"}}} in .vscode/mcp.json (OAuth) |
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:
X-Twitter-Cookie and X-Twitter-Proxy (and X-Twitter-Chat-Passcode for DMs) with every
request. The server uses them for that request only and stores nothing.Guide: twittrapi.com/docs/hosted-mcp#account-tools-post-like-dm.
Every tool call is one billed API call on your account.
claude mcp add twittrapi --env TWITTRAPI_API_KEY=your-key -- npx -y twittrapi-mcpOpen 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.
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"
}
}
}
}Any client that can start a stdio server works. The command is npx -y twittrapi-mcp.
| Variable | Required | Description |
|---|---|---|
TWITTRAPI_API_KEY | one of the two keys | Your TwittrAPI key. Sent as the X-API-KEY header. |
RAPIDAPI_KEY | one of the two keys | RapidAPI key. Used only when TWITTRAPI_API_KEY is not set. |
RAPIDAPI_HOST | no | Host of your RapidAPI listing. Default twitter-aio.p.rapidapi.com. |
TWITTRAPI_BASE_URL | no | API base URL for the direct API. Default https://api.twittrapi.com. |
TWITTRAPI_RESPONSE_FORMAT | no | simple (default) or raw. See Response format. |
TWITTRAPI_X_COOKIE | no | Cookie of your own logged-in x.com session. Turns on the account tools together with TWITTRAPI_X_PROXY. |
TWITTRAPI_X_PROXY | no | Your proxy for the account tools, http://user:pass@host:port. |
TWITTRAPI_X_CHAT_PASSCODE | no | Your X Chat passcode. Adds send_dm, accept_dm_request, decline_dm_request and message text in list_dm_conversations. |
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.
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".
These tools read public data and are always available. The account tools are added when you configure your X session.
| Tool | What it does |
|---|---|
get_user_by_username | Profile by handle, including the numeric user ID |
get_user_by_id | Profile by numeric user ID |
username_to_id | Resolve a handle to its user ID |
users_by_ids | Profiles for up to 500 user IDs at once |
get_user_tweets | A user's tweets |
get_user_tweets_and_replies | A user's tweets and replies |
get_user_media | A user's tweets with photos or videos |
get_followers | A user's followers |
get_following | Accounts a user follows |
get_verified_followers | A user's verified followers |
get_user_affiliates | Accounts affiliated with an organization |
get_friendships_batch | Whether one account follows up to 50 others, and back |
get_user_about_batch | "About this account" for up to 20 handles |
search_tweets | Search with X operators; Top, Latest, People, Photos or Videos |
get_tweet | A tweet and its reply thread |
tweets_by_ids | Up to 100 tweets by ID at once |
get_tweet_retweets | Users who retweeted a tweet |
get_tweet_quotes | Tweets quoting a tweet |
get_tweet_replies | Only the replies to a tweet |
get_tweet_thread | The author's own thread around a tweet |
get_list_details | List name, owner and counts |
get_list_tweets | Tweets from a list's members |
get_list_members | Members of a list |
get_community | Community details |
get_community_about | A community's About page: rules, moderators, members |
get_community_tweets | Tweets in a community |
search_communities | Find communities by keyword |
get_trends | Trending topics for a location (WOEID) |
get_trend_locations | Locations that have trends, with their WOEIDs |
get_space | 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.
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 |
|---|---|
create_tweet | Post a tweet; optional quote (quoteUrl), poll (pollChoices) and reply limit |
reply_to_tweet | Reply to a tweet |
delete_tweet | Delete one of your tweets |
like_tweet, unlike_tweet | Like or unlike a tweet |
retweet, unretweet | Retweet or undo a retweet |
bookmark_tweet, unbookmark_tweet | Add or remove a bookmark |
follow_user, unfollow_user | Follow or unfollow (by userId or username) |
list_dm_conversations | Your DM inbox |
send_dm | Send a direct message (needs TWITTRAPI_X_CHAT_PASSCODE) |
list_dm_requests | Pending message requests; does not accept them or mark them as seen |
accept_dm_request | Accept a one-to-one request and send the first reply (needs TWITTRAPI_X_CHAT_PASSCODE) |
decline_dm_request | Delete a request from your inbox; the sender is not told (needs TWITTRAPI_X_CHAT_PASSCODE) |
create_list | Create a list |
add_list_member, remove_list_member | Add or remove a list member |
create_draft, list_drafts | Save a draft, list your drafts |
list_bookmark_folders, list_bookmark_folder_tweets | Your bookmark folders and the tweets in one (X Premium) |
search_bookmarks | Search your bookmarks |
list_community_memberships | Communities you are a member of |
list_articles, get_article | Your X Articles, drafts or published, and one article (X Premium) |
create_article, update_article | Save a new article as a draft, change one (X Premium) |
publish_article, unpublish_article, delete_article | 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"
}readOnlyHint: false (deletions and undo actions also
destructiveHint: true), so clients ask before running them.X-Twitter-Cookie, X-Twitter-Proxy and X-Twitter-Chat-Passcode headers, or, on the hosted
server, the session saved in the dashboard for an OAuth grant with the x:write scope. See
HTTP mode.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):
format argument, "simple" or "raw";TWITTRAPI_RESPONSE_FORMAT=raw (the format argument 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.
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.
API errors come back as tool errors with a short explanation, for example:
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> or Authorization: Bearer <key> for the direct APIx-rapidapi-key: <key> for RapidAPI, plus x-rapidapi-host: <host> for a listing other than
twitter-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... and X-Twitter-Proxy: http://user:pass@host:port
(both or neither; 400 otherwise), plus X-Twitter-Chat-Passcode for the DM tools. The values
are used for that request only, never stored, logged or returned.x:write scope: 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 optional account argument (@handle or numeric user ID; the default
account when it is left out), the server instructions name the accounts, and the free
list_x_accounts tool 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"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:
401 and
WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="mcp";/.well-known/oauth-protected-resource/mcp and /.well-known/oauth-protected-resource, and
relays the dashboard's RFC 8414 metadata at /.well-known/oauth-authorization-server;OAUTH_CACHE_SECONDS (30) and invalid ones for 5 s, and accepts
only tokens whose audience is MCP_PUBLIC_URL;x:write scope, 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 within OAUTH_CACHE_SECONDS.
Invalid or revoked tokens get 401 with error="invalid_token"; if the dashboard cannot be
reached the answer is 503 with Retry-After, so clients keep their tokens.| Variable | Default | Description |
|---|---|---|
PORT, HOST | 3333, 127.0.0.1 | Listen address (the Docker image uses 3000, 0.0.0.0) |
TWITTRAPI_BASE_URL | https://api.twittrapi.com | Gateway the tools call |
TWITTRAPI_RESPONSE_FORMAT | simple | Default format of tool results |
MCP_PUBLIC_URL | – | Public URL of /mcp, e.g. https://mcp.twittrapi.com/mcp. Token audience. |
OAUTH_ISSUER | – | Authorization server, e.g. https://app.twittrapi.com |
OAUTH_INTROSPECTION_SECRET | – | Shared secret with the dashboard (32+ characters). OAuth is on when these three are set. |
OAUTH_INTROSPECTION_URL | $OAUTH_ISSUER/api/oauth/introspect | Internal URL of the introspection endpoint |
OAUTH_METADATA_URL | $OAUTH_ISSUER/.well-known/oauth-authorization-server | Where the relayed metadata is fetched |
OAUTH_CACHE_SECONDS | 30 | Cache for valid tokens (max 300). Revocations take effect within this time. |
MAX_CONCURRENCY_PER_KEY | 8 | Requests in flight per key and instance; more get 429 with Retry-After: 1. 0 turns it off. |
MCP_EVENTS_URL | – | Optional. Usage events, one per tool call, POSTed in batches to this URL (the TwittrAPI dashboard: /api/mcp/events). No tool arguments, results, X session or API key; the key only as a SHA-256 hash. |
MCP_EVENTS_SECRET | OAUTH_INTROSPECTION_SECRET | Bearer secret for MCP_EVENTS_URL. |
MAX_BODY_BYTES | 262144 | Larger request bodies get 413 |
REQUEST_TIMEOUT_MS | 90000 | Requests running longer get 504 |
ALLOWED_ORIGINS | – | Comma-separated Origin allowlist for browser clients (DNS rebinding protection) |
TRUST_PROXY | – | 1 to log the client IP from X-Forwarded-For |
LOG_LEVEL | info | debug, info, warn, error |
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 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.
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.jsQuestions, bugs or a higher rate limit: email [email protected] or open an issue in this repository. Service status: twittrapi.com/status. News and changes: the TwittrAPI Telegram channel (link on the website).
MIT
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add twittrapi -- npx -y twittrapi-mcp{
"mcpServers": {
"twittrapi": {
"env": {
"TWITTRAPI_API_KEY": ""
},
"args": [
"-y",
"twittrapi-mcp"
],
"command": "npx"
}
}
}code --add-mcp '{"name":"twittrapi","env":{"TWITTRAPI_API_KEY":""},"args":["-y","twittrapi-mcp"],"command":"npx"}'[mcp_servers.twittrapi]
command = "npx"
args = ["-y", "twittrapi-mcp"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/twittrapi-mcp to learn what the "Twittrapi Mcp" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
claude mcp add twittrapi --env TWITTRAPI_API_KEY=your-key -- npx -y twittrapi-mcp
claude mcp add --transport http twittrapi https://your-host.example.com/mcp --header "X-API-KEY: your-key"npx -y twittrapi-mcp --http --port 3333 --host 0.0.0.0
npx @modelcontextprotocol/inspector -e TWITTRAPI_API_KEY=your-key node dist/index.jsdocker run -p 3000:3000 -e MCP_PUBLIC_URL=... -e OAUTH_ISSUER=... -e OAUTH_INTROSPECTION_SECRET=... twittrapi-mcpThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: its endpoint did not list its tools to an anonymous client, which usually means it asks for an API key or a sign-in. The four checks that need a live server are left out, and the grade tops out at B until we can read its tools.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/twittrapi-mcp)Nothing comparable is listed yet.
v1.6.0Release notesv1.5.0Release notesv1.4.0Release notesv1.3.0Release notesv1.2.0Release notesv1.1.0Release notesv1.0.0Release notesv0.4.0Release notesv0.3.2Release notesv0.3.1Release notesv0.3.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "twittrapi-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.