ajitashwath/x-mcp

X MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with X (formerly Twitter) API, enabling AI assistants to search tweets, analyze users, retrieve trending topics, and more.

Features

Core Functionality

• Tweet Search: Search for tweets with advanced filtering options
• User Analytics: Get detailed user information and statistics
• User Timeline: Retrieve recent tweets from specific users
• Tweet Details: Get comprehensive information about specific tweets
• Hashtag Analysis: Analyze hashtag usage and trends
• Trending Topics: Get trending topics by location (placeholder)
• Tweet Posting: Post new tweets (placeholder for future implementation)

MCP Integration

• Full compatibility with MCP-enabled AI assistants
• Structured tool definitions with comprehensive input schemas
• Error handling and graceful degradation
• Bearer token authentication support

Prerequisites

• Python 3.9 or higher
• X API Bearer Token (Essential plan or higher)
• MCP-compatible client (Claude Desktop)

Installation

1. Clone and Setup

git clone https://github.com/ajitashwath/x-mcp.git
cd x-mcp
chmod +x setup.sh
./setup.sh

2. Manual Installation

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

3. Configure API Credentials

Edit the .env file with your X API credentials:

TWITTER_BEARER_TOKEN=your_bearer_token_here
TWITTER_API_KEY=your_api_key_here
TWITTER_API_SECRET=your_api_secret_here
TWITTER_ACCESS_TOKEN=your_access_token_here
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret_here

Note: Currently, only the Bearer Token is required for read operations. Future versions will support write operations using the full OAuth credentials.

4. Getting X API Credentials

1. Visit the X Developer Portal
2. Create a new app or use an existing one
3. Navigate to your app's "Keys and Tokens" section
4. Generate/copy your Bearer Token
5. For write operations (future), you'll also need API keys and access tokens

Configuration

MCP Client Configuration

Add the server to your MCP client configuration. For Claude Desktop, add to claude_config.json:

{
    "mcpServers": {
        "x-mcp": {
            "command": "python",
            "args": ["path/to/your/x-mcp/server.py"],
            "env": {
                "TWITTER_BEARER_TOKEN": "your_bearer_token_here"
            }
        }
    }
}

Environment Variables

*Required for future write operations

Usage

Available Tools

1. Search Tweets

{
    "name": "search_tweets",
    "parameters": {
        "query": "your search query",
        "max_results": 10,
        "result_type": "recent"
    }
}

Parameters:

• query (required): Search query string
• max_results (optional): Number of results (1-100, default: 10)
• result_type (optional): "recent", "popular", or "mixed" (default: "recent")

2. Get User Information

{
    "name": "get_user_info",
    "parameters": {
        "username": "elonmusk"
    }
}

Parameters:

• username (required): Twitter username without @

3. Get User Tweets

{
    "name": "get_user_tweets",
    "parameters": {
        "username": "elonmusk",
        "max_results": 20,
        "exclude_retweets": true
    }
}

Parameters:

• username (required): Twitter username without @
• max_results (optional): Number of tweets (5-100, default: 10)
• exclude_retweets (optional): Exclude retweets (default: false)

4. Get Tweet Details

{
    "name": "get_tweet_details",
    "parameters": {
        "tweet_id": "1234567890123456789"
    }
}

Parameters:

• tweet_id (required): The ID of the tweet

5. Analyze Hashtag

{
    "name": "analyze_hashtag",
    "parameters": {
        "hashtag": "AI",
        "days": 3
    }
}

Parameters:

• hashtag (required): Hashtag to analyze (with or without #)
• days (optional): Analysis period in days (1-7, default: 1)

6. Get Trending Topics

{
    "name": "get_trending_topics",
    "parameters": {
        "woeid": 1
    }
}

Parameters:

• woeid (optional): Location WOEID (default: 1 for worldwide)

Note: Currently a placeholder - requires X API v1.1 access

7. Post Tweet

{
    "name": "post_tweet",
    "parameters": {
        "text": "Hello, world!",
        "reply_to_id": "1234567890123456789"
    }
}

Parameters:

• text (required): Tweet content (max 280 characters)
• reply_to_id (optional): ID of tweet to reply to

Note: Currently a placeholder - requires write permissions

Examples

Example Conversations

Search for AI-related tweets:

User: "Search for recent tweets about artificial intelligence"
Assistant: Uses search_tweets with query "artificial intelligence"

Get user information:

User: "Tell me about @elonmusk's Twitter profile"
Assistant: Uses get_user_info with username "elonmusk"

Analyze trending hashtag:

User: "What's the buzz around #AI lately?"
Assistant: Uses analyze_hashtag with hashtag "AI"

Testing

Test the Server

# Run the server directly (for debugging)
python server.py

# Test with environment variables
TWITTER_BEARER_TOKEN=your_token python server.py

Common Issues

1. "Bearer Token not configured"

   • Ensure your .env file exists and contains the correct token
   • Check that the token is valid and has the necessary permissions

2. "API Error: 429"

   • You've hit the rate limit
   • Wait for the rate limit to reset or upgrade your X API plan

3. "User not found" or "Tweet not found"

   • Verify the username/ID is correct
   • The user/tweet might be private or deleted

Development

Project Structure

x-mcp/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── .env.example          # Environment template
├── .env                  # Your actual environment variables
├── .gitignore           # Git ignore patterns
├── setup.sh             # Setup script
├── claude_config.json   # Example Claude Desktop config
└── README.md           # This file

Dependencies

• mcp: Model Context Protocol library
• httpx: Modern HTTP client
• python-dotenv: Environment variable management

Adding New Features

1. Add the tool definition in setup_handlers()
2. Implement the async method
3. Add error handling
4. Update the README

API Limits and Considerations

X API Limits (Essential Plan)

• 10,000 tweet reads per month
• Read-only access
• Real-time tweet retrieval

Rate Limiting

The server implements proper error handling for rate limits but does not include client-side rate limiting. Consider implementing this for production use.

Troubleshooting

Debug Mode

Set logging level to DEBUG for detailed information:

logging.basicConfig(level=logging.DEBUG)

Common Solutions

1. Server not starting: Check Python version and dependencies
2. API errors: Verify credentials and API plan limits
3. MCP connection issues: Check client configuration and server path

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Check the X API Documentation
• Review MCP Documentation
• Open an issue on the repository

Changelog

Version 1.0.0

• Initial release
• Basic search and user information tools
• MCP server implementation
• Bearer token authentication