Twitter Read

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

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:

1. Create a Twitter Developer account
2. Create a new App
3. 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!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. 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.