TweetAPI MCP server
Commit Nov 5, 2026Allows AI agents to read public Twitter data including profiles, tweets, lists, communities, and trends using the TweetAPI service.
Also known as tweetapi/tweetapi-mcp
- Stars
- 2
- Tools
- 1
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 5, 2026
- License
- MIT
What is TweetAPI MCP?
TweetAPI allows AI agents to read public Twitter data including profiles, tweets, lists, communities, and trends using the TweetAPI service. It exposes 1 tool, such as responseFormat.
Summary generated from the project's README
About TweetAPI MCP server
Accessing public social media data through AI agents is possible with tweetapi-mcp. This server connects to the TweetAPI service to provide read-only access to profiles, tweets, lists, communities, Spaces, and trending topics. It is designed for developers who want to integrate real-time social data into their AI workflows without needing to manage complex API interactions manually.
Users can choose between a hosted setup using OAuth and Streamable HTTP or a local installation via stdio. The hosted version requires a TweetAPI account and allows you to select which API key powers the connection, offering 100 free units to new users. For local deployment, you must use Node 18 or newer and pnpm, providing a TWEETAPI_API_KEY through environment variables.
The server includes 47 live tools for data retrieval and a separate set of free documentation tools. While live tools consume API units, the documentation tools like tweetapi_docs_search are free and do not require an API key. The system is strictly read-only, meaning it cannot post content, send direct messages, or modify account settings.
What you can do with it
- 1Analyze trending topicsAsk an AI agent to find out what is currently trending in a specific country or location.
- 2Monitor user engagementHave an AI client retrieve specific metrics for a tweet to understand its reach.
- 3Research community discussionsInstruct an agent to pull recent posts and member information from a specific community.
- 4Check API credit balanceAsk the agent to verify how many API units remain on the connected account.
Written from the project's README. Every use case is checked against a quote from it.
TweetAPI MCP tools 1
Detected from the READMEresponseFormat
Configuration
TWEETAPI_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletweetapi/tweetapi-mcp is public and reachablegithub.com/tweetapi/tweetapi-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-05github.com/tweetapi/tweetapi-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model1 tool description and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTweetAPI MCP
MCP server for TweetAPI, a third-party Twitter data API. It lets AI agents read public Twitter data (search, profiles, followers, timelines, lists, communities, Spaces and trends) and look up TweetAPI's own docs.
TweetAPI is an independent service and is not affiliated with X Corp.
Hosted server
The easiest way to use it is the hosted server. You sign in with your TweetAPI account and pick which API key backs the connection. New accounts get 100 free API units and no card is needed.
https://mcp.tweetapi.com/mcp
Codex:
codex mcp add tweetapi --url https://mcp.tweetapi.com/mcp
codex mcp login tweetapi
Claude Code:
claude mcp add --transport http --scope user tweetapi https://mcp.tweetapi.com/mcp
claude mcp login tweetapi
Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"tweetapi": {
"url": "https://mcp.tweetapi.com/mcp"
}
}
}
The hosted server uses Streamable HTTP and OAuth. More setup notes are in the agents guide.
Run it locally
You can also run the server yourself over stdio with an API key from the TweetAPI dashboard. Node 18 or newer and pnpm are required.
git clone https://github.com/tweetapi/tweetapi-mcp.git
cd tweetapi-mcp
pnpm install
pnpm run build
Then point your MCP client at it:
{
"mcpServers": {
"tweetapi": {
"command": "node",
"args": ["/path/to/tweetapi-mcp/dist/bin.js", "--live"],
"env": {
"TWEETAPI_API_KEY": "your_tweetapi_key_here"
}
}
}
}
Without --live, only the docs tools are available and no API key is needed.
Tools
Docs (free, no API calls): tweetapi_docs_search, tweetapi_endpoint_lookup,
tweetapi_docs_get_page, tweetapi_sdk_guidance, tweetapi_tool_catalog.
Live data (47 read-only tools):
- Users: profile by username or ID, batches of up to 100, About this account, tweets, tweets and replies, Photos, Videos, Highlights and Articles tabs, followers and following (profiles or IDs), verified followers, subscriptions, affiliates, similar accounts, Lists and List memberships, follow check.
- Tweets: search, details with replies, metrics only, batches of up to 200 by ID, quotes, retweets, hidden replies, translation.
- Lists: details, tweets, members, followers, search.
- Communities: details, tweets, media, members, search.
- Spaces: details and audio stream URL.
- Trends: trending topics worldwide, by country or by location, and the locations X supports.
- Account:
tweetapi_account_usage, the units left on the API key behind the connection.
Each live tool call makes exactly one TweetAPI request and is billed like any other API call. Tools never paginate on their own; the agent passes the cursor when it wants the next page.
Live tools are read-only. There are no tools for posting, DMs, follows, profile edits, account cookies or billing. The only account tool is the free read-only usage check for the connection's own API key.
Live tool results
- Live tools declare an MCP output schema and return the same JSON as
structuredContentand as a text block. - Each result has
retrievedAt(when the MCP server got the response),completeness(page cursor, batch items not returned, or a single object),output(format and omitted fields), andcost(a unit estimate from the published pricing rules, not a billing record). responseFormat: "compact"is optional on profile, post, and List-page tools. It keeps full post text, IDs, links, original dates, counts, and cursors, never drops items, and lists the dropped fields inoutput.fieldsOmitted. The default staysfull, which returns TweetAPI's JSON unchanged.tweetapi_tweet_metricsreturns its own short projection, so itsoutput.formatismetrics,output.fieldsOmittedlists what it leaves out, andoutput.textTruncatedmatchesresult.tweet.textTruncated.- On the four X v1.1 follower and following ID and list tools, a
nextCursorof"0"means the last page.paginationkeeps the"0", andcompletenessreports no next cursor. - An empty page that still has a
nextCursorsays so incompleteness.note. X often sends a cursor at the end of a feed, so if the next page is empty too, stop: empty pages are billed. - Post, profile, list, community, and Space fields accept the matching
x.comortwitter.comlink, and username fields accept@handles. Seesrc/identifiers.tsfor the exact rules. tweetapi_trendstakescountryorwoeid, not both. Sending both is rejected before any request is made.tweetapi_account_usagereads the units left on the API key behind the connection. It is free and counts toward the per-minute limit.- Errors carry
details.layer(mcp_input,mcp_connection,tweetapi_api_key,tweetapi_api,network),retryable,retryAfterSecondswhen TweetAPI sentRetry-After, and a cost estimate. The server never retries on its own.
docs/client-verification.md lists which client behaviors are covered by local tests and which still need a manual check with a real client.
Hosted service
This repo is also the source for the service at mcp.tweetapi.com. In HTTP mode it accepts
dashboard-issued OAuth tokens with the tweetapi:read scope, resolves the backing API key on the
server, and never sends the bearer token upstream. It depends on TweetAPI's OAuth server, so it is
not meant to be self-hosted as is. See docs/security.md and
docs/deployment.md for how it works.
docker build -t tweetapi-mcp .
docker run --rm -p 3100:3100 -e MCP_ALLOWED_HOSTS=localhost,127.0.0.1 tweetapi-mcp
curl http://localhost:3100/healthz
Development
pnpm install
pnpm run check
pnpm run check:release
The checks cover formatting, Markdown lint, TypeScript, unit tests, stdio and HTTP smoke tests, and a secret scan. Tests mock the docs and the API; they never call the live TweetAPI API.
Security
Please report vulnerabilities privately. See SECURITY.md.
License
TweetAPI MCP questions
What tools does TweetAPI MCP provide?
It exposes 1 tool, including responseFormat.
Can I use this server to post tweets or send DMs?
No, the live tools are read-only. There are no tools for posting, DMs, follows, profile edits, account cookies, or billing.
How much does it cost to use the tools?
Each live tool call makes one TweetAPI request and is billed according to the service's pricing rules. New accounts receive 100 free API units.
Is there a way to use the server without an API key?
Yes, if you run the server without the --live flag, only the documentation tools are available and no API key is required.
What kind of Twitter data can I access?
You can access public data such as profiles, tweets, replies, followers, following, lists, communities, Spaces, and trending topics.