mbelinky/x-mcp-server

An enhanced Model Context Protocol (MCP) server for X that adds OAuth 2.0 support, v2 API media uploads, and comprehensive rate limiting to the original implementation.
✨ Features
- **Post Tweets**: Create text tweets with optional media attachments (images, GIFs)
- **Search Tweets**: Search X with customizable result count
- **Delete Tweets**: Remove your tweets programmatically
- **Dual Authentication**: Support for both OAuth 1.0a and OAuth 2.0
- **Media Upload**: Post images using the appropriate API version for each auth method
- **Rate Limiting**: Built-in protection for X's API limits
- **Type Safety**: Full TypeScript implementation with Zod validation
🔄 API Version Handling
This server intelligently uses different X API versions based on authentication method and operation:
OAuth 1.0a
- **Tweet operations**: Uses v2 API endpoints
- **Media upload**: Uses v1.1 endpoint (upload.twitter.com)
- **Delete fallback**: Automatically falls back to v1.1 when v2 fails
OAuth 2.0
- **All operations**: Uses v2 API endpoints exclusively
- **Media upload**: Uses v2 endpoint (api.x.com/2/media/upload)
- **No v1.1 access**: Cannot fall back to v1.1 due to authentication restrictions
Why Different Endpoints?
- **v1.1**: Legacy API, being phased out but still works with OAuth 1.0a
- **v2**: Modern API with better features but some endpoints have issues
- **Media**: OAuth 2.0 tokens cannot access v1.1 media endpoints, must use v2
- **Delete**: v2 delete endpoint currently has issues (500 errors), v1.1 works as fallback
📋 Prerequisites
Before you begin, you'll need:
1. An X Developer Account (sign up at developer.x.com)
2. An X App created in the Developer Portal
3. API credentials (detailed setup below)
4. Node.js 18+ installed
🔐 Authentication Setup
This server supports two authentication methods. Choose based on your needs:
- **OAuth 1.0a**: Simpler setup, works with all features including v1.1 fallbacks
- **OAuth 2.0**: Modern authentication, required for some newer features
Setting Up Your X App
1. **Create a Developer Account**:
- Go to developer.x.com
- Sign in with your Twitter account
- Apply for developer access if you haven't already
2. **Create a New App**:
- Navigate to the Twitter Developer Portal
- Click "Projects & Apps" → "New Project"
- Give your project a name
- Select your use case
- Create a new App within the project
3. **Configure App Permissions**:
- In your app settings, go to "User authentication settings"
- Click "Set up"
- Enable OAuth 1.0a and/or OAuth 2.0
- Set App permissions to "Read and write"
- Add Callback URLs:
- For OAuth 1.0a: http://localhost:3000/callback
- For OAuth 2.0: http://localhost:3000/callback
- Set Website URL (can be your GitHub repo)
OAuth 1.0a Setup
1. **Get Your Credentials**:
- In your app's "Keys and tokens" tab
- Copy your API Key and API Key Secret
- Generate Access Token and Secret (click "Generate")
- Make sure the access token has "Read and Write" permissions
2. **Required Credentials**:
OAuth 2.0 Setup
1. **Get Your Client Credentials**:
- In your app's "Keys and tokens" tab
- Find OAuth 2.0 Client ID and Client Secret
- Save these for the next step
2. **Generate User Tokens**:
Option A - Use our helper script:
Option B - Manual setup:
- Use the OAuth 2.0 flow with PKCE
- Required scopes: tweet.read, tweet.write, users.read, media.write, offline.access
- Exchange authorization code for access token
3. **Required Credentials**:
🚀 Installation
For Claude Desktop
1. **Install via NPM** (Recommended):
Edit your Claude Desktop configuration file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json