X MCP Server - Enhanced Edition

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:

An X Developer Account (sign up at developer.x.com)
An X App created in the Developer Portal
API credentials (detailed setup below)
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

Create a Developer Account:
- Go to developer.x.com
- Sign in with your Twitter account
- Apply for developer access if you haven't already
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
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

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

Required Credentials:

API_KEY=your_api_key_here
API_SECRET_KEY=your_api_secret_key_here
ACCESS_TOKEN=your_access_token_here
ACCESS_TOKEN_SECRET=your_access_token_secret_here

OAuth 2.0 Setup

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
Generate User Tokens:

Option A - Use our helper script:
```
# Clone this repository first
git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install

# Run the OAuth2 setup script
node scripts/oauth2-setup.js
```
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

Required Credentials:

AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id_here
OAUTH2_CLIENT_SECRET=your_client_secret_here
OAUTH2_ACCESS_TOKEN=your_access_token_here
OAUTH2_REFRESH_TOKEN=your_refresh_token_here

🚀 Installation

For Claude Desktop

Install via NPM (Recommended):

Edit your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "API_KEY": "your_api_key_here",
        "API_SECRET_KEY": "your_api_secret_key_here",
        "ACCESS_TOKEN": "your_access_token_here",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret_here"
      }
    }
  }
}

For OAuth 2.0:

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "AUTH_TYPE": "oauth2",
        "OAUTH2_CLIENT_ID": "your_client_id",
        "OAUTH2_CLIENT_SECRET": "your_client_secret",
        "OAUTH2_ACCESS_TOKEN": "your_access_token",
        "OAUTH2_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Install from Source:

git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install
npm run build

Then update your config to point to the local installation:

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "node",
      "args": ["/path/to/twitter-mcp/build/index.js"],
      "env": {
        // ... your credentials
      }
    }
  }
}

Restart Claude Desktop

For Claude Code (CLI)

Install the server globally and add it to Claude:

# For OAuth 1.0a
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "API_KEY=your_api_key" \
  --env "API_SECRET_KEY=your_secret_key" \
  --env "ACCESS_TOKEN=your_access_token" \
  --env "ACCESS_TOKEN_SECRET=your_access_token_secret"

# For OAuth 2.0
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "AUTH_TYPE=oauth2" \
  --env "OAUTH2_CLIENT_ID=your_client_id" \
  --env "OAUTH2_CLIENT_SECRET=your_client_secret" \
  --env "OAUTH2_ACCESS_TOKEN=your_access_token" \
  --env "OAUTH2_REFRESH_TOKEN=your_refresh_token"

🛠️ Available Tools

Once installed, Claude can use these tools:

`post_tweet`

Post a new tweet with optional media attachments and replies.

Example prompts:

"Post a tweet saying 'Hello from Claude!'"
"Tweet this image with the caption 'Check out this view!'" (attach image)
"Reply to tweet ID 123456789 with 'Great point!'"

`search_tweets`

Search for tweets with customizable result count (10-100).

Example prompts:

"Search for tweets about #MachineLearning"
"Find 50 recent tweets mentioning @ClaudeAI"
"Search for tweets about TypeScript tutorials"

`delete_tweet`

Delete a tweet by its ID.

Example prompts:

"Delete tweet with ID 1234567890"
"Remove my last tweet (provide the ID)"

Note: Due to temporary Twitter API issues, OAuth 1.0a uses v1.1 fallback for deletion.

📸 Media Upload Notes

When using Claude to post tweets with images:

Use file paths: Save your image to disk and provide the file path
Base64 limitation: While the server supports base64 encoded images, Claude cannot extract base64 from pasted images
Other clients: Base64 support remains available for programmatic use and other MCP clients

Example usage:

# ✅ Recommended for Claude
"Post tweet with image at /Users/me/photos/sunset.png"

# ❌ Not currently supported in Claude
"Post this image: [pasting an image directly]"

# ✅ Works programmatically
// In code, you can still use base64
{
  "text": "Hello world!",
  "media": [{
    "data": "iVBORw0KGgoAAAANS...",
    "media_type": "image/png"
  }]
}

🧪 Testing

The project includes comprehensive tests:

# Run all tests
npm test

# Run specific test suites
npm test -- --testNamePattern="OAuth"
npm test -- --testPathPattern="unit"

🔧 Development

Setup

git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install

Commands

npm run build    # Build TypeScript
npm run dev      # Run in development mode
npm test         # Run tests
npm run lint     # Lint code
npm run format   # Format code

Environment Variables

Create a .env file for local development:

# OAuth 1.0a
API_KEY=your_api_key
API_SECRET_KEY=your_api_secret_key
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret

# OAuth 2.0 (if using)
AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id
OAUTH2_CLIENT_SECRET=your_client_secret
OAUTH2_ACCESS_TOKEN=your_access_token
OAUTH2_REFRESH_TOKEN=your_refresh_token

# Optional
DEBUG=true  # Enable debug logging

✅ OAuth 2.0 Media Upload Support

Media uploads now work with both OAuth 1.0a and OAuth 2.0!

OAuth 1.0a uses the v1.1 media upload endpoint ✓
OAuth 2.0 uses the v2 media upload endpoint ✓
Both authentication methods support posting tweets with images (JPEG, PNG, GIF)

Note: OAuth 2.0 requires the media.write scope for media uploads.

⚠️ Known Issues

Tweet Deletion (Temporary)

Twitter's v2 delete endpoint is currently experiencing issues (returning 500 errors). The MCP server handles this gracefully:

OAuth 1.0a: Automatically falls back to v1.1 delete endpoint ✅
OAuth 2.0: Cannot use v1.1 endpoint, will show helpful error message ⚠️

This is a temporary Twitter API issue. Once resolved, both auth methods will use v2 deletion.

🐛 Troubleshooting

Common Issues

"Could not authenticate you"

Verify all credentials are correct
Check that your app has "Read and Write" permissions
For OAuth 1.0a, regenerate your access tokens
For OAuth 2.0, ensure tokens have required scopes

"Rate limit exceeded"

Twitter has strict rate limits (especially on free tier)
Wait 15 minutes and try again
Consider upgrading your Twitter API access level

"Media upload failed"

Check file size (max 5MB for images)
Verify file format (JPEG, PNG, GIF only)
For OAuth 2.0, ensure media.write scope is included

"403 Forbidden"

Your app may lack required permissions
Check your Twitter Developer Portal settings
Ensure your access level supports the operation

Debug Mode

Enable detailed logging by setting the DEBUG environment variable:

{
  "env": {
    "DEBUG": "true",
    // ... other credentials
  }
}

Log Locations

Windows: %APPDATA%\Claude\logs\mcp-server-twitter.log
macOS: ~/Library/Logs/Claude/mcp-server-twitter.log

📚 Resources

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

🔒 Privacy Policy

This MCP server:

Does not store any user data: All Twitter/X API credentials are stored locally on your machine
Does not log sensitive information: API keys and tokens are never logged
Only communicates with Twitter/X: No data is sent to any third-party services
Processes data locally: All operations happen on your machine
Respects rate limits: Built-in protection for Twitter's API limits

Your tweets, searches, and media remain private between you and Twitter/X.

📧 Support

Email: mbelinky@gmail.com
Issues: GitHub Issues
Documentation: GitHub Wiki

For security vulnerabilities, please email directly instead of creating a public issue.

📄 License

MIT

🙏 Acknowledgments

This is an enhanced fork of @enescinar/twitter-mcp that adds:

OAuth 2.0 authentication support
Twitter/X API v2 media upload for OAuth 2.0
Automatic v1.1 fallback for OAuth 1.0a
Comprehensive rate limiting for free tier
Enhanced error handling and debugging
Programmatic OAuth 2.0 token generation script

Original implementation by @enescinar

X (Twitter) MCP Server - Enhanced Edition

README Documentation

X MCP Server - Enhanced Edition

✨ Features

🔄 API Version Handling

OAuth 1.0a

OAuth 2.0

Why Different Endpoints?

📋 Prerequisites

🔐 Authentication Setup

Setting Up Your X App

OAuth 1.0a Setup

OAuth 2.0 Setup

🚀 Installation

For Claude Desktop

For Claude Code (CLI)

🛠️ Available Tools

post_tweet

search_tweets

delete_tweet

📸 Media Upload Notes

🧪 Testing

🔧 Development

Setup

Commands

Environment Variables

✅ OAuth 2.0 Media Upload Support

⚠️ Known Issues

Tweet Deletion (Temporary)

🐛 Troubleshooting

Common Issues

Debug Mode

Log Locations

📚 Resources

🤝 Contributing

🔒 Privacy Policy

📧 Support

📄 License

🙏 Acknowledgments

Quick Install

Quick Actions

Key Features

`post_tweet`

`search_tweets`

`delete_tweet`