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

Installation

Prerequisites

• Node.js 18 or higher
• Twitter API credentials (Bearer Token or API Key + Secret)

From Source

git clone 
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: