X (Twitter)

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.

- 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

This server intelligently uses different X API versions based on authentication method and operation:

- 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

- 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

- 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
- An X Developer Account (sign up atdeveloper.x.com)
- An X App created in the Developer Portal
- API credentials (detailed setup below)
- Node.js 18+ installed

- Navigate to theTwitter Developer Portal
- Click "Projects & Apps" → "New Project"
- Give your project a name
- Select your use case
- Create a new App within the project

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

# 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

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

{ "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" } } } }

{ "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" } } } }

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 } } } }

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"

Once installed, Claude can use these tools:

Post a new tweet with optional media attachments and replies.

- "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 for tweets with customizable result count (10-100).

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

- "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.

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

# ✅ 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" }] }

The project includes comprehensive tests:

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

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

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

Create a.envfile 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

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 themedia.writescope for media uploads.

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.

- 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

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

- Check file size (max 5MB for images)
- Verify file format (JPEG, PNG, GIF only)
- For OAuth 2.0, ensuremedia.writescope is included

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

Enable detailed logging by setting theDEBUGenvironment variable:

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

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

- Twitter API Documentation
- MCP Documentation
- OAuth 2.0 Setup Guide
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request

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

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

Connect AI assistants like Cursor to Google Chat and beyond — enabling smart, extensible collaboration across chat platforms.