Skip to main content
Glama

X(Twitter) MCP Server

by cjkcr

X(Twitter) MCP Server

smithery badge

English | ไธญๆ–‡

An MCP server to create, manage and publish X/Twitter posts directly through Claude code and Gemini CLI chat.

Note: This project is modified from vidhupv/x-mcp, with added reply functionality for tweets.

Features

๐Ÿ” Dual Authentication Support

  • โœ… OAuth 1.0a: For write operations (posting tweets, retweeting, etc.)

  • โœ… OAuth 2.0: For read operations (getting tweets, searching, etc.)

  • โœ… Automatic Client Selection: System automatically chooses the best authentication method

  • โœ… Smart Fallback: Automatically falls back to OAuth 1.0a when OAuth 2.0 is unavailable

๐Ÿ“ Tweet Management

  • โœ… Create draft tweets

  • โœ… Create draft tweet threads

  • โœ… Create draft replies to existing tweets

  • โœ… List all drafts

  • โœ… Publish drafts (tweets, threads, and replies)

  • โœ… Reply to tweets directly (without creating drafts)

  • โœ… Retweet existing tweets

  • โœ… Quote tweet with comments

  • โœ… Create draft quote tweets

  • โœ… Delete drafts

  • โœ… Auto-delete failed drafts (configurable)

  • โœ… Draft preservation on publish failure (configurable)

๐Ÿ“ท Media Support

  • โœ… Upload media files (images, videos, GIFs)

  • โœ… Create tweets with media attachments

  • โœ… Add alt text for accessibility

  • โœ… Get media file information

๐Ÿ“– Tweet Retrieval (Enhanced)

  • โœ… Get tweet content and information (with dual authentication support)

  • โœ… Search recent tweets (improved error handling)

  • โœ… Batch retrieve multiple tweets (more stable connections)

  • โœ… Detailed error diagnostics and suggestions

  • โœ… API connection testing tools

Quick Setup

Installing via Smithery

To install X(Twitter) MCP Server for Claude code automatically via Smithery:

npx -y @smithery/cli install x-mcp --client claude

Manual Installation for Claude code

  1. Clone the repository:

git clone https://github.com/yourusername/x-mcp.git
  1. Install UV globally using Homebrew in Terminal:

brew install uv
  1. Create claude_desktop_config.json:

    • For MacOS: Open directory ~/Library/Application Support/Claude/ and create the file inside it

    • For Windows: Open directory %APPDATA%/Claude/ and create the file inside it

  2. Add this configuration to claude_desktop_config.json:

Basic Configuration (OAuth 1.0a Only)

{ "mcpServers": { "x_mcp": { "command": "uv", "args": [ "--directory", "/path/to/x-mcp", "run", "x-mcp" ], "env": { "TWITTER_API_KEY": "your_api_key", "TWITTER_API_SECRET": "your_api_secret", "TWITTER_ACCESS_TOKEN": "your_access_token", "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret" } } } }

Recommended Configuration (OAuth 1.0a + OAuth 2.0 Dual Authentication)

{ "mcpServers": { "x_mcp": { "command": "uv", "args": [ "--directory", "/path/to/x-mcp", "run", "x-mcp" ], "env": { "TWITTER_API_KEY": "your_api_key", "TWITTER_API_SECRET": "your_api_secret", "TWITTER_ACCESS_TOKEN": "your_access_token", "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret", "TWITTER_BEARER_TOKEN": "your_bearer_token" } } } }

๐Ÿ’ก Recommended to use dual authentication configuration: Adding TWITTER_BEARER_TOKEN can significantly improve the stability and success rate of tweet retrieval functions.

  1. Get your X/Twitter API credentials:

    • Go to X API Developer Portal

    • Create a project

    • In User Authentication Settings: Set up with Read and Write permissions, Web App type

    • Set Callback URL to http://localhost/ and Website URL to http://example.com/

    • Generate and copy all keys and tokens from Keys and Tokens section

  2. Update the config file:

    • Replace /path/to/x-mcp with your actual repository path

    • Add your X/Twitter API credentials

  3. Quit Claude completely and reopen it

Configuration for Gemini CLI

If you want to use this MCP server with Gemini CLI instead of Claude code:

  1. Install Gemini CLI:

npm install -g @google/gemini-cli
  1. Create or update your MCP configuration file:

    • Create a file named ~/.gemini/settings.json

    • Add the following configuration:

{ "mcpServers": { "x_mcp": { "command": "uv", "args": [ "--directory", "/path/to/x-mcp", "run", "x-mcp" ], "env": { "TWITTER_API_KEY": "your_api_key", "TWITTER_API_SECRET": "your_api_secret", "TWITTER_ACCESS_TOKEN": "your_access_token", "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret" } } } }
  1. Start Gemini CLI with MCP support:

Restart gemini cli
  1. Update the config file:

    • Replace /path/to/x-mcp with your actual repository path

    • Add your X/Twitter API credentials

Advanced Configuration

Auto-Delete Failed Drafts

When tweet publishing fails, you can choose whether to automatically delete drafts:

  • Enable auto-delete (default): Automatically delete drafts when publishing fails to avoid accumulating invalid drafts

  • Disable auto-delete: Preserve drafts when publishing fails, allowing manual retry or modification

Configuration Methods

  1. Via Environment Variable: Add "AUTO_DELETE_FAILED_DRAFTS": "true" or "false" in your configuration file

  2. Via Commands: Use "Enable auto-delete failed drafts" or "Disable auto-delete failed drafts"

  3. Check Status: Use "Check current auto-delete configuration"

Usage Examples

Works with both Claude code and Gemini CLI:

  • "Tweet 'Just learned how to tweet through AI - mind blown! ๐Ÿค–โœจ'"

  • "Create a thread about the history of pizza"

  • "Show me my draft tweets"

  • "Publish this draft!"

  • "Delete that draft"

  • "Reply to tweet 1234567890 with 'Great point! Thanks for sharing.'"

  • "Create a draft reply to tweet 1234567890 saying 'I completely agree with this perspective.'"

  • "Retweet tweet 1234567890"

  • "Quote tweet 1234567890 with comment 'This is exactly what I was thinking!'"

  • "Create a draft quote tweet for 1234567890 with comment 'Amazing insight here'"

  • "Upload image /path/to/image.jpg with alt text 'Beautiful sunset over the mountains'"

  • "Create tweet with media 'Check out this amazing photo!' using media IDs 123456789"

  • "Create draft tweet with media 'My latest project' and attach /path/to/video.mp4"

  • "Enable auto-delete failed drafts"

  • "Disable auto-delete failed drafts"

  • "Check current auto-delete configuration"

  • "Get tweet 1234567890 content and information"

  • "Search for tweets containing 'AI OR artificial intelligence' from the last 7 days"

  • "Get information for tweets 123456789, 987654321, 555666777"

Troubleshooting

Basic Issues

If not working:

  • Make sure UV is installed globally (if not, uninstall with pip uninstall uv and reinstall with brew install uv)

  • Or find UV path with which uv and replace "command": "uv" with the full path

  • Verify all X/Twitter credentials are correct

  • Check if the x-mcp path in config matches your actual repository location

๐Ÿ”ง API Connection Testing

Quick Diagnosis:

test api connection

Running this command in Claude will:

  • Test OAuth 1.0a and OAuth 2.0 connections

  • Check API permissions and limitations

  • Provide detailed diagnostic information and suggestions

Run Test Script:

cd /path/to/x-mcp python test_tweet_functions.py

๐Ÿšจ 401 Unauthorized Error Fix

Problem Symptoms:

  • Getting "401 Unauthorized" error when posting tweets

  • Can post tweets but cannot retrieve tweets

Solutions:

  1. Add Bearer Token (Recommended):

    "env": { "TWITTER_API_KEY": "your_api_key", "TWITTER_API_SECRET": "your_api_secret", "TWITTER_ACCESS_TOKEN": "your_access_token", "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret", "TWITTER_BEARER_TOKEN": "your_bearer_token" }
  2. Regenerate API Credentials:

  3. Check Project Settings:

    • User authentication settings: Read and write permissions

    • App type: Web App

    • Callback URL: http://localhost/

    • Website URL: http://example.com/

๐Ÿ“– Tweet Retrieval Issues

Dual Authentication Benefits:

  • OAuth 2.0 for read operations (more stable)

  • OAuth 1.0a for write operations (required)

  • Automatic fallback handling

Common Errors and Solutions:

Error Code

Cause

Solution

401

Authentication failed

Check API credentials, regenerate tokens

403

Insufficient permissions

Upgrade API plan or check permission settings

404

Tweet not found

Verify tweet ID, check if tweet is public

429

Rate limit exceeded

Wait 15 minutes or upgrade API plan

API Plan Limitations:

  • Free Users: Basic functionality with limitations

  • Basic ($100/month): Full read functionality

  • Pro ($5000/month): Advanced features and higher limits

๐Ÿ” Detailed Diagnostic Steps

  1. Check Authentication Status:

    test api connection
  2. Verify Configuration:

    • Confirm all environment variables are set

    • Check paths are correct

    • Validate API key formats

  3. Test Specific Functions:

    search for tweets containing "hello" get tweet 1234567890 content
  4. Review Detailed Logs:

    • Check Claude Desktop console

    • Review MCP server logs

    • Note specific error messages

Credits

This project is based on the excellent work by Vidhu Panhavoor Vasudevan in the original x-mcp repository.

What's New in This Fork

  • ๐Ÿ†• OAuth Dual Authentication System - Support for OAuth 1.0a + OAuth 2.0, automatic selection of best authentication method

  • ๐Ÿ†• 401 Error Fix - Resolved authentication issues when retrieving tweets

  • ๐Ÿ†• Smart Client Selection - Read operations prefer OAuth 2.0, write operations use OAuth 1.0a

  • ๐Ÿ†• Enhanced Error Handling - Detailed error diagnostics and English error messages

  • ๐Ÿ†• API Connection Testing Tool - Built-in connection testing and diagnostic functionality

  • โœ… Reply to tweets functionality - Create draft replies and reply directly to existing tweets

  • โœ… Retweet functionality - Simple retweets and quote tweets with comments

  • โœ… Media functionality - Upload images, videos, GIFs with alt text support

  • โœ… Tweet retrieval functionality - Get tweet content, search tweets, batch retrieve multiple tweets

  • โœ… Enhanced draft management - Improved draft preservation on publish failure, support for all draft types

Special thanks to the original author for creating the foundation of this MCP server!

Detailed Documentation

For more detailed functionality descriptions and usage guides, please refer to:

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables creating, managing, and publishing X/Twitter posts, threads, and replies directly through Claude chat. Supports draft management with the ability to create, list, publish, and delete tweet drafts.

  1. Features
    1. ๐Ÿ” Dual Authentication Support
    2. ๐Ÿ“ Tweet Management
    3. ๐Ÿ“ท Media Support
    4. ๐Ÿ“– Tweet Retrieval (Enhanced)
  2. Quick Setup
    1. Installing via Smithery
    2. Manual Installation for Claude code
    3. Configuration for Gemini CLI
  3. Advanced Configuration
    1. Auto-Delete Failed Drafts
  4. Usage Examples
    1. Troubleshooting
      1. Basic Issues
      2. ๐Ÿ”ง API Connection Testing
      3. ๐Ÿšจ 401 Unauthorized Error Fix
      4. ๐Ÿ“– Tweet Retrieval Issues
      5. ๐Ÿ” Detailed Diagnostic Steps
    2. Credits
      1. What's New in This Fork
    3. Detailed Documentation

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/cjkcr/x-mcp'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server