GeLi2001/x-mcp-server

X MCP Server

A Model Context Protocol (MCP) server that provides access to X (formerly Twitter) API for basic utilities. This server allows AI assistants and other MCP clients to interact with X/Twitter through a standardized interface.

Features

• 🔐 Simple Bearer Token Authentication - Easy setup with just one token
• 👤 User Information - Get user profiles by username or ID
• 🐦 Read-Only Operations - Get tweets, user information, and search (no posting)
• 🔍 Search - Search for tweets with various filters and options
• 📝 User Timeline - Retrieve a user's recent tweets
• 🛠️ MCP Tools - Standardized tools for AI integration
• ⚡ Async/Await - Built with Tokio for high performance

Installation

From crates.io

cargo install x-mcp-server

From source

git clone https://github.com/yourusername/x-mcp-server
cd x-mcp-server
cargo build --release

Quick Start

1. Get X API Credentials

1. Go to the X Developer Portal
2. Create a new app or use an existing one
3. Generate your API keys and access tokens
4. Make sure your app has the necessary permissions

2. Set Environment Variables

Create a .env file or set environment variables:

export X_CONSUMER_KEY="your_consumer_key"
export X_CONSUMER_SECRET="your_consumer_secret"
export X_ACCESS_TOKEN="your_access_token"
export X_ACCESS_TOKEN_SECRET="your_access_token_secret"

Or copy .env.example to .env and fill in your credentials.

3. Run the Server

x-mcp-server

The server will start and listen for MCP requests on stdin/stdout.

Configuration

The server can be configured using environment variables:

Available Tools

The server provides the following MCP tools:

get_user

Get user information by username or user ID.

Parameters:

• identifier (string): Username (without @) or user ID
• is_user_id (boolean, optional): Whether the identifier is a user ID (default: false)

Example:

{
  "identifier": "elonmusk",
  "is_user_id": false
}

post_tweet

Post a new tweet.

Parameters:

• text (string): The text content of the tweet
• reply_to (string, optional): Tweet ID to reply to

Example:

{
  "text": "Hello, world! 🌍",
  "reply_to": "1234567890"
}

search_tweets

Search for tweets.

Parameters:

• query (string): Search query
• max_results (integer, optional): Maximum number of results (1-100, default: 10)
• include_users (boolean, optional): Include user information (default: false)
• include_metrics (boolean, optional): Include tweet metrics (default: false)

Example:

{
  "query": "MCP OR \"Model Context Protocol\"",
  "max_results": 20,
  "include_users": true,
  "include_metrics": true
}

get_tweet

Get a specific tweet by ID.

Parameters:

• tweet_id (string): The tweet ID

Example:

{
  "tweet_id": "1234567890"
}

get_user_tweets

Get a user's recent tweets.

Parameters:

• identifier (string): Username or user ID
• is_user_id (boolean, optional): Whether the identifier is a user ID (default: false)
• max_results (integer, optional): Maximum number of tweets (1-100, default: 10)

Example:

{
  "identifier": "elonmusk",
  "max_results": 5
}

Library Usage

You can also use this as a Rust library:

[dependencies]
x-mcp-server = "0.1"

use x_mcp_server::{XClient, auth::OAuthCredentials};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create credentials
    let credentials = OAuthCredentials::from_env()?;
    let client = XClient::new(credentials);

    // Get user info
    let user = client.get_user_by_username("elonmusk").await?;
    println!("{:#?}", user);

    // Post a tweet
    let tweet = client.post_tweet("Hello from Rust! 🦀", None).await?;
    println!("Posted tweet: {}", tweet.id);

    Ok(())
}

MCP Integration

This server implements the Model Context Protocol specification. You can integrate it with any MCP-compatible client:

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "x-mcp-server": {
      "command": "x-mcp-server",
      "env": {
        "X_CONSUMER_KEY": "your_key",
        "X_CONSUMER_SECRET": "your_secret",
        "X_ACCESS_TOKEN": "your_token",
        "X_ACCESS_TOKEN_SECRET": "your_token_secret"
      }
    }
  }
}

Other MCP Clients

Any MCP client can connect to this server using stdio transport.

Development

Building

cargo build

Testing

cargo test

Running with Debug Logs

RUST_LOG=debug cargo run

API Limits

Please be aware of X API rate limits:

• User lookup: 300 requests per 15-minute window
• Tweet posting: 300 tweets per 15-minute window
• Search: 180 requests per 15-minute window
• User timeline: 1500 requests per 15-minute window

The server does not implement rate limiting, so ensure your usage stays within these limits.

Security

• API credentials are never logged or exposed
• OAuth 1.0a signatures are generated securely
• All HTTP requests use HTTPS

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under either of

• Apache License, Version 2.0, ( or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license ( or http://opensource.org/licenses/MIT)

at your option.

Related

• Model Context Protocol
• X API Documentation
• MCP Rust SDK