How do I use twitter-read?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by Polsia-Inc

Overview Schema Related Servers Score Discussions

JavaScript

Remote

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 build

From npm (future)

npm install -g @polsia/twitter-read-mcp

Configuration

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_here

Note: 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 1882163408476512603

2. `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 hours

3. `get_replies`

Get all replies to a specific tweet.

Parameters:

tweet_id (required): The ID of the tweet
max_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 1882163408476512603

4. `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 week

Rate Limiting

The server enforces Twitter API v2 rate limits:

500 requests per 15-minute window
Each tool response includes requestsRemaining field
Requests beyond the limit return a rate limit error

Development

Building

npm run build

Watch Mode

npm run watch

Testing Locally

Run the MCP server directly:

export TWITTER_BEARER_TOKEN=your_token
npm run dev

The server communicates via stdio, so you'll need an MCP client to interact with it.

Architecture

Language: TypeScript
MCP SDK: @modelcontextprotocol/sdk v1.x
Twitter Client: twitter-api-v2 for Twitter API v2
Transport: 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 window
Missing Twitter API credentials: Environment variables not set
Invalid tweet ID: Tweet doesn't exist or is private
Search 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 tools

get_mentionsB

Get recent @mentions of the authenticated account

ParametersJSON Schema

Name	Required	Description	Default
`since_date`	No	ISO 8601 date string (e.g., 2026-01-20T00:00:00Z). Only tweets after this date will be returned.
`max_results`	No	Maximum number of mentions to return (5-100, default: 10)

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully carries the burden of behavioral disclosure. It does not mention authentication needs, rate limits, pagination, or the format of results, leaving significant gaps for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no unnecessary words. It is front-loaded but could benefit from additional context while remaining efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity, few parameters, and no output schema, the description is minimally adequate. It lacks details on what is returned (e.g., full tweet objects) or any additional behavioral context, but it covers the core purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it does not elaborate on parameter usage or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource '@mentions of the authenticated account', specifying exactly what the tool retrieves. It implicitly distinguishes from sibling tools like 'get_replies' by focusing on mentions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates the tool retrieves recent mentions but provides no explicit guidance on when to use it versus alternatives like 'get_replies' or 'search_tweets'. No when-not-to-use or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_repliesB

Get replies to a specific tweet

ParametersJSON Schema

Name	Required	Description	Default
`tweet_id`	Yes	The ID of the tweet to fetch replies for
`max_results`	No	Maximum number of replies to return (5-100, default: 10)

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description only states 'Get replies' without disclosing safety, auth requirements, or rate limits. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is efficient and front-loaded. Could be improved by structuring with more detail, but current length is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks explanation of return values or output structure (no output schema). For a simple read tool, it is somewhat complete but missing output details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%; baseline 3 applies. Description adds no extra meaning beyond the schema—just restates the tool's purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'replies to a specific tweet'. It distinguishes well from sibling tools like get_mentions and search_tweets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No mention of prerequisites or contexts like when to prefer get_replies over get_mentions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tweet_metricsA

Get engagement metrics for a specific tweet including likes, retweets, replies, and impressions

ParametersJSON Schema

Name	Required	Description	Default
`tweet_id`	Yes	The ID of the tweet to fetch metrics for

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the metrics returned (likes, retweets, replies, impressions), which is helpful. However, it omits details about rate limits, authentication needs, or whether the operation is read-only (though it's implied).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that conveys all necessary information without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter, no output schema), the description is complete enough for an AI agent to understand what the tool does and what it returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes tweet_id comprehensively (100% coverage). The description adds no new semantic information about the parameter beyond 'specific tweet', which is already clear from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: retrieving engagement metrics for a specific tweet, listing specific metrics like likes, retweets, replies, and impressions. This distinguishes it from siblings like get_mentions or search_tweets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a tweet's engagement data is needed, but does not explicitly state when to use this tool versus alternatives like get_mentions (which focuses on mentions) or get_replies (which focuses on replies). No exclusion criteria are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_tweetsB

Search for tweets matching a query and return results with engagement metrics

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query string (supports Twitter search operators)
`max_results`	No	Maximum number of tweets to return (10-100, default: 10)
`start_time`	No	ISO 8601 date string for earliest tweet (e.g., 2026-01-20T00:00:00Z)

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Lacks details on rate limits, pagination, or search archive type. Only mentions returning engagement metrics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence (12 words) front-loads the core action and output. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, description is too brief. Missing return format, pagination info, and any usage context for a search tool with 3 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 3 parameters with descriptions (100% coverage). Description adds no extra meaning beyond what schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it searches tweets matching a query and returns engagement metrics. Differentiates from siblings like get_mentions and get_replies by focusing on general search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings or alternatives. Does not mention context for search vs. mentions/replies.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

4 tool updatesv1.0.0May 26, 2026
- First observedget_mentions
- First observedget_replies
- First observedget_tweet_metrics
- First observedsearch_tweets

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Disambiguation5/5

Each tool targets a distinct operation: mentions, replies, metrics, and search. No overlap in purpose, and descriptions clearly differentiate them.

Naming Consistency5/5

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.

Tool Count5/5

Four tools is appropriate for a read-only Twitter server, covering the main data retrieval needs without being too sparse or excessive.

Completeness4/5

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.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

twitterapi-mcp-server A
io.github.kaitoInfra
Twitter/X read-only MCP server — 12 tools: search, users, tweets, followers, timelines, trends.
Social Media Search
121
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
SocialGPT AOAuth
io.github.scrollmark
Social media analytics, video analysis, and competitor intel for any MCP-compatible AI agent.
Social Media Image & Video Processing Research & Data
510
UnifAPIOAuth
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2

Related MCP Servers

x-mcp
Social Media App Automation Communication
Infatoshi
F
license
A
quality
D
maintenance
An 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.
Updated 5 months ago (2026-03-24 09:16 UTC)
15
52
-
X(Twitter) V2 MCP Server
Social Media Search
NexusX-MCP
A
license
Not graded
quality
D
maintenance
An MCP server for interacting with the Twitter/X API v2, enabling AI assistants to retrieve tweets, post content, reply, quote, and more programmatically.
Updated a year ago (2025-04-20 13:28 UTC)
2,013
13
MIT
Twitter MCP
Social Media Communication
isteamhq
A
license
A
quality
D
maintenance
MCP server for Twitter/X enabling AI agents to search, post, reply, and engage with tweets.
Updated 5 months ago (2026-04-17 08:58 UTC)
14
21
1
MIT
twitterapis
Social Media Search
TwitterAPIs
A
license
A
quality
B
maintenance
MCP server for the Twitter/X read API, enabling search, user profiles, tweets, followers, and more via natural language.
Updated a day ago (2026-09-05 22:18 UTC)
94
149
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Polsia-Inc/twitter-read-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Twitter Read MCP Server

Features

Installation

Prerequisites

From Source

From npm (future)

Configuration

Twitter API Credentials

Environment Variables

MCP Configuration

Usage

Available Tools

1. get_tweet_metrics

2. get_mentions

3. get_replies

4. search_tweets

Rate Limiting

Development

Building

Watch Mode

Testing Locally

Architecture

Error Handling

Contributing

Roadmap

License

Support

Credits

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

1. `get_tweet_metrics`

2. `get_mentions`

3. `get_replies`

4. `search_tweets`