X MCP Server

An MCP server that uses X (Twitter) APIs to search through X and get current events data.

Features

• Search User Tweets: Find the most recent tweets from specific users
• Trending Topics: Get current trending topics worldwide or by location
• Topic Search: Search for specific user-generated topics and hashtags

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Set up X API credentials as environment variables:

export X_BEARER_TOKEN="your_bearer_token"
export X_API_KEY="your_api_key"
export X_API_SECRET="your_api_secret"
export X_ACCESS_TOKEN="your_access_token"
export X_ACCESS_TOKEN_SECRET="your_access_token_secret"

Note:

• X_BEARER_TOKEN is required for basic functionality (user tweets and topic search)
• All credentials are required for trending topics feature

Getting X API Credentials

1. Go to Twitter Developer Portal
2. Create a new app or use an existing one
3. Generate your API keys and tokens
4. Copy the Bearer Token, API Key, API Secret, Access Token, and Access Token Secret

Usage

Run the server using fastmcp:

# Development mode with auto-reload
fastmcp dev src/X-mcp.py

# Production mode
fastmcp run src/X-mcp.py

Or run directly with Python:

python src/X-mcp.py

Available Tools

1. search_user_tweets

Search through the most recent tweets of a specific user.

Parameters:

• username (str): The X/Twitter username (without @)
• max_results (int, optional): Maximum number of tweets to return (default: 10, max: 100)

Example:

search_user_tweets(username="elonmusk", max_results=20)

2. search_trending_topics

Get current trending topics on X/Twitter.

Parameters:

• woeid (int, optional): Where On Earth ID for location (default: 1 for Worldwide)
  • Common WOEIDs: 1=Worldwide, 23424977=USA, 2459115=NYC

Example:

search_trending_topics(woeid=1)  # Get worldwide trends

3. search_topics

Search for specific user-generated topics on X/Twitter.

Parameters:

• query (str): The search query/topic to search for
• max_results (int, optional): Maximum number of tweets to return (default: 10, max: 100)
• sort_order (str, optional): Sort order - "recency" or "relevancy" (default: "recency")

Example:

search_topics(query="AI news", max_results=25, sort_order="relevancy")

API Rate Limits

The X API has rate limits. This server uses wait_on_rate_limit=True to automatically handle rate limiting by waiting when limits are reached.

License

MIT