X MCP Server
A Model Context Protocol (MCP) server for X (Twitter) integration. Provides 16 tools for reading timelines, posting, searching, engagement (likes, retweets, bookmarks), and user lookup. Designed for use with Claude desktop and other MCP-compatible clients.
Features
- Timeline & Search — Home timeline, search recent posts (7-day window)
- Post Management — Create, reply, quote, delete posts with optional media
- Engagement — Like/unlike, retweet/undo, bookmark/unbookmark
- User Lookup — Get user profiles and their recent posts
- Media Upload — Images (PNG, JPEG, GIF, WEBP) and videos (MP4, MOV, AVI, WEBM, M4V) via v2 upload API
- Dual Auth — OAuth 1.0a for post operations, OAuth 2.0 for media upload (v1.1 upload was sunset June 2025)
- Rate Limiting — Automatic per-endpoint rate limit tracking with clear error messages
- TypeScript — Full type safety, modular file structure
Prerequisites
- Node.js >= 18.0.0
- X (Twitter) Developer Account
- Claude desktop app (or any MCP-compatible client)
X API Access & Pricing
| Tier | Cost | Post Reads | Post Writes | Notes |
|------|------|-----------|-------------|-------|
| Free | $0 | ~100/month | ~500/month | No likes/follows; media upload requires OAuth 2.0 |
| Basic | $200/month | 10,000/month | 3,000/month | Search, limited read access |
| Pro | $5,000/month | 1,000,000/month | 300,000/month | Full search, filtered stream |
| Pay-Per-Use | Credit-based | ~$0.005/read | Varies | Launched Feb 2026, 2M reads cap |
Like and Follow endpoints were removed from the Free tier in August 2025.
Follows/Blocks endpoints are Enterprise-only as of 2025.
Installation
git clone https://github.com/DataWhisker/x-mcp-server.git
cd x-mcp-server
npm install
npm run build
Authentication
The server supports two authentication methods. You need at least one configured.
OAuth 1.0a (Required for basic operations)
Works for all post/engagement/search/user operations.
| Environment Variable | Description |
|---------------------|-------------|
| TWITTER_API_KEY | Consumer Key (API Key) |
| TWITTER_API_SECRET | Consumer Secret (API Key Secret) |
| TWITTER_ACCESS_TOKEN | User Access Token |
| TWITTER_ACCESS_SECRET | User Access Token Secret |
Setup: In the X Developer Portal:
- Create a project and app
- Enable OAuth 1.0a under "User authentication settings"
- Set permissions to "Read and Write"
- Generate Consumer Keys and Access Tokens
OAuth 2.0 (Required for media upload)
The v1.1 media upload endpoint was sunset in June 2025. Media upload now requires OAuth 2.0 via the v2 upload API.
Option A — Direct access token:
| Variable | Description |
|----------|-------------|
| TWITTER_OAUTH2_ACCESS_TOKEN | OAuth 2.0 user access token (expires in 2 hours) |
Option B — Auto-refresh (recommended for long-running servers):
| Variable | Description |
|----------|-------------|
| TWITTER_CLIENT_ID | OAuth 2.0 Client ID |
| TWITTER_CLIENT_SECRET | OAuth 2.0 Client Secret (optional for public clients) |
| TWITTER_OAUTH2_REFRESH_TOKEN | OAuth 2.0 Refresh Token |
Tokens are auto-refreshed and persisted to ~/.x-mcp-tokens.json.
Setup: In the X Developer Portal:
- In your app settings, enable OAuth 2.0
- Set type to "Confidential client" or "Public client"
- Add a callback URL
- Request scopes:
tweet.read, tweet.write, users.read, media.write, offline.access, like.read, like.write, bookmark.read, bookmark.write
Claude Desktop Configuration
Add to %APPDATA%/Claude/claude_desktop_config.json:
{
"mcpServers": {
"x": {
"command": "node",
"args": ["C:/path/t
... [View full README on GitHub](https://github.com/DataWhisker/x-mcp-server#readme)
