twitter-read
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., "@twitter-read Search for tweets from @polsiaHQ"
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.
Twitter Read MCP Server
An MCP (Model Context Protocol) server for reading Twitter/X engagement data and metrics. Enables AI agents to measure tweet performance, track mentions, analyze replies, and search tweets with engagement metrics.
Features
Get Tweet Metrics: Fetch likes, retweets, replies, quotes, bookmarks, and impressions for any tweet
Get Mentions: Retrieve recent @mentions with engagement data
Get Replies: Access all replies to a specific tweet with metrics
Search Tweets: Search Twitter with engagement metrics included
Built-in Rate Limiting: Enforces Twitter API limits (500 requests per 15 minutes)
OAuth 2.0 Support: Compatible with Twitter API v2 authentication
Related MCP server: X(Twitter) V2 MCP Server
Installation
Prerequisites
Node.js 18 or higher
Twitter API credentials (Bearer Token or API Key + Secret)
From Source
git clone <repository-url>
cd twitter-read-mcp
npm install
npm run buildFrom npm (future)
npm install -g @polsia/twitter-read-mcpConfiguration
Twitter API Credentials
You need Twitter API access. Get credentials from Twitter Developer Portal:
Create a Twitter Developer account
Create a new App
Generate credentials
Environment Variables
Create a .env file or set environment variables:
# Option 1: Bearer Token (recommended for read-only access)
TWITTER_BEARER_TOKEN=your_bearer_token_here
# Option 2: API Key + Secret (for OAuth 2.0)
TWITTER_API_KEY=your_api_key_here
TWITTER_API_SECRET=your_api_secret_hereNote: Bearer token is simpler for read-only operations. API Key + Secret is required for user-context operations like getting your own mentions.
MCP Configuration
Add to your MCP settings file (e.g., Claude Desktop config):
{
"mcpServers": {
"twitter-read": {
"command": "twitter-read-mcp",
"env": {
"TWITTER_BEARER_TOKEN": "your_bearer_token_here"
}
}
}
}Or if installed from source:
{
"mcpServers": {
"twitter-read": {
"command": "node",
"args": ["/path/to/twitter-read-mcp/build/index.js"],
"env": {
"TWITTER_BEARER_TOKEN": "your_bearer_token_here"
}
}
}
}Usage
Available Tools
1. get_tweet_metrics
Get engagement metrics for a specific tweet.
Parameters:
tweet_id(required): The ID of the tweet
Returns:
{
"tweet_id": "1234567890",
"text": "Tweet content here",
"created_at": "2026-01-25T00:00:00.000Z",
"author_id": "1234567890",
"metrics": {
"likes": 42,
"retweets": 8,
"replies": 5,
"quotes": 2,
"bookmarks": 10,
"impressions": 5000
},
"requestsRemaining": 498
}Example:
Get metrics for tweet 18821634084765126032. get_mentions
Get recent @mentions of your account.
Parameters:
since_date(optional): ISO 8601 date (e.g., "2026-01-20T00:00:00Z")max_results(optional): Number of mentions to return (5-100, default: 10)
Returns:
{
"mentions": [
{
"tweet_id": "1234567890",
"text": "@yourhandle great work!",
"created_at": "2026-01-25T00:00:00.000Z",
"author_id": "9876543210",
"metrics": {
"likes": 5,
"retweets": 1,
"replies": 0,
"quotes": 0
}
}
],
"count": 1,
"requestsRemaining": 497
}Example:
Show me mentions from the last 24 hours3. get_replies
Get all replies to a specific tweet.
Parameters:
tweet_id(required): The ID of the tweetmax_results(optional): Number of replies to return (5-100, default: 10)
Returns:
{
"replies": [
{
"tweet_id": "1234567891",
"text": "This is a reply",
"created_at": "2026-01-25T01:00:00.000Z",
"author_id": "9876543210",
"metrics": {
"likes": 2,
"retweets": 0,
"replies": 1,
"quotes": 0
}
}
],
"count": 1,
"requestsRemaining": 496
}Example:
Get all replies to tweet 18821634084765126034. search_tweets
Search for tweets matching a query with engagement metrics.
Parameters:
query(required): Search query (supports Twitter search operators)max_results(optional): Number of tweets to return (10-100, default: 10)start_time(optional): ISO 8601 date for earliest tweet
Returns:
{
"tweets": [
{
"tweet_id": "1234567890",
"text": "Tweet matching your query",
"created_at": "2026-01-25T00:00:00.000Z",
"author_id": "1234567890",
"metrics": {
"likes": 100,
"retweets": 20,
"replies": 10,
"quotes": 5
}
}
],
"count": 1,
"query": "from:polsiaHQ",
"requestsRemaining": 495
}Example:
Search for tweets from @polsiaHQ in the last weekRate Limiting
The server enforces Twitter API v2 rate limits:
500 requests per 15-minute window
Each tool response includes
requestsRemainingfieldRequests beyond the limit return a rate limit error
Development
Building
npm run buildWatch Mode
npm run watchTesting Locally
Run the MCP server directly:
export TWITTER_BEARER_TOKEN=your_token
npm run devThe server communicates via stdio, so you'll need an MCP client to interact with it.
Architecture
Language: TypeScript
MCP SDK:
@modelcontextprotocol/sdkv1.xTwitter Client:
twitter-api-v2for Twitter API v2Transport: stdio (standard MCP transport)
Authentication: Bearer Token or OAuth 2.0 PKCE
Error Handling
All tools return structured error responses:
{
"error": "Error message",
"code": "ERROR_CODE",
"requestsRemaining": 499
}Common errors:
Rate limit exceeded: Too many requests in 15-minute windowMissing Twitter API credentials: Environment variables not setInvalid tweet ID: Tweet doesn't exist or is privateSearch query too complex: Simplify your search query
Contributing
This project is part of the Polsia ecosystem. Contributions are welcome!
Fork the repository
Create a feature branch
Make your changes
Submit a pull request
Roadmap
OAuth 2.0 PKCE flow for user authentication
Caching layer for frequently accessed tweets
Batch operations for multiple tweets
Historical data fetching (7-day window)
User profile metrics
List management tools
License
MIT License - See LICENSE file for details
Support
Documentation: Twitter API v2 Docs
MCP Specification: Model Context Protocol
Issues: Report bugs and feature requests on GitHub
Credits
Built by Polsia for measuring marketing performance on Twitter/X. Powered by the Model Context Protocol from Anthropic.
Available Tools
4 toolsget_mentionsB
Get recent @mentions of the authenticated account
Inputs: since_date, max_results.
get_repliesB
Get replies to a specific tweet
Inputs: tweet_id (required), max_results.
get_tweet_metricsA
Get engagement metrics for a specific tweet including likes, retweets, replies, and impressions
Inputs: tweet_id (required).
search_tweetsB
Search for tweets matching a query and return results with engagement metrics
Inputs: query (required), max_results, start_time.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct operation: mentions, replies, metrics, and search. No overlap in purpose, and descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern (get_mentions, get_replies, get_tweet_metrics, search_tweets), making the naming predictable and easy to understand.
Four tools is appropriate for a read-only Twitter server, covering the main data retrieval needs without being too sparse or excessive.
The tool set covers mentions, replies, metrics, and search, but lacks a tool to fetch the text of a specific tweet directly (metrics-only tool assumes you already have the tweet). This is a minor gap for a read server.
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.
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Your agent needs X/Twitter data — who follows a competitor, what a community is posting, who quoted that tweet, what is trending in Japan. Normally that means applying for an X developer account, passing app review, and managing a quota per endpoint. **What you can ask for** • "Who follows @stripe, and which of them are verified?" • "Pull every reply and quote on this tweet and summarise what people object to." • "List this community's moderators and its posts this week." • "What is trending in Japan right now?" • "Give me the full thread context behind this link, including the long-form article." **How to use it** Point any MCP client at https://mcp.aisa.one/twitter-api/mcp and sign in with OAuth — there is no key to create or paste. 29 read tools: users (profile, about, batch lookup by id, search, followers, verified followers, followings, follow check), tweets (timeline, latest, mentions, advanced search, replies, quotes, retweeters, thread context, articles), communities, lists, Spaces and trends. **Why this rather than the source** No developer account to apply for, no app review, no per-endpoint quota to manage. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Ask for a handle's followers here, then ask the same agent for that brand's search traffic, its backlinks, or the people to contact — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/social/mcp for X plus Instagram, Reddit, Pinterest and YouTube; https://mcp.aisa.one/gtm/mcp for those plus Similarweb and Apollo.
X Ads (Twitter Ads) MCP server: run X campaigns, ad groups, ads and reports from AI.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that provides AI agents with full access to the X (Twitter) API for posting, searching, and managing engagement through natural language. It supports comprehensive tools for tweet management, media uploads, and account analytics across multiple MCP-compatible clients.1563MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for interacting with the Twitter/X API v2, enabling AI assistants to retrieve tweets, post content, reply, quote, and more programmatically.2,530 npm13MIT
- AlicenseAqualityCmaintenanceMCP server for Twitter/X enabling AI agents to search, post, reply, and engage with tweets.1415 npm2MIT
- AlicenseAqualityBmaintenanceMCP server for the Twitter/X API, enabling search, user profiles, tweets, followers, and more via natural language.941,114 npm6MIT