twitter-x-research-mcp

MCP server for the X (Twitter) API v2. Read-only research tools for searching tweets, looking up users, and monitoring trends.

Quick Start

1. Get a Bearer Token from developer.x.com

2. Add to your MCP client config:

{
  "mcpServers": {
    "x-research": {
      "command": "npx",
      "args": ["-y", "twitter-x-research-mcp"],
      "env": {
        "X_API_BEARER_TOKEN": "your_token_here"
      }
    }
  }
}

That's it. Works with Claude Desktop, Cursor, Claude Code, and any MCP client.

Config file locations

| Client | Config file | |--------|------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | | Cursor | .cursor/mcp.json (project) or global settings | | Claude Code | .mcp.json (project root) |

Tools

8 read-only research tools:

| Tool | Description | |------|-------------| | x_search | Search tweets (recent 7 days or full archive) | | x_get_tweet | Look up one or more tweets by ID | | x_get_user | Get user profile by username or ID | | x_get_user_tweets | Get a user's posted tweets | | x_get_user_mentions | Get tweets mentioning a user | | x_get_followers | Get a user's followers or following list | | x_get_trends | Get trending topics by location | | x_get_engagement | Get likes, retweets, or quote tweets for a tweet |

Tool Toggles

By default all 8 tools are enabled. To expose only specific tools:

{
  "env": {
    "X_API_BEARER_TOKEN": "your_token",
    "X_MCP_TOOLS": "x_search,x_get_user,x_get_tweet"
  }
}

Set X_MCP_TOOLS=all (or omit it) to enable everything.

API Tier Requirements

• Basic ($200/mo): All tools work. Search limited to last 7 days.
• Pro ($5K/mo): Full-archive search via x_search with mode="archive".
• Pay-per-use: All tools work. ~$0.005/read.
• Free: Very limited. Most read endpoints are restricted.

Development

If you want to contribute or run from source:

git clone https://github.com/EllypsisAI/x-api-mcp.git
cd x-api-mcp
npm install
npm run build
npm test

License

MIT — Ellypsis AI