Labsco
mbelinky logo

X (Twitter)

★ 20

from mbelinky

Enhanced MCP server for Twitter/X with OAuth 2.0 support, v2 API media uploads, smart v1.1 fallbacks, and comprehensive rate limiting. Post tweets with text/media, search, and delete tweets programmatically.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#email#automation#social-media#git#maps#security#video-editing

X MCP Server - Enhanced Edition

npm version

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

🛠️ 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.

📚 Resources

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. 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

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