X MCP Server 🐦

A powerful Model Context Protocol (MCP) Server for interacting with the X (Twitter) API v2. This server enables AI assistants like ChatGPT, Claude, and other MCP-compatible clients to automate Twitter/X actions.

Note: This server is limited to endpoints available in the Free tier of X API.

📋 Table of Contents

• Features

• Getting X API Credentials

• Installation

• Configuration

• Connecting to AI Clients

  • Claude Desktop

  • ChatGPT / OpenAI

  • Other MCP Clients

• Available Tools

• Rate Limits

• License

✨ Features

• 54+ automation tools for X/Twitter

• Post, delete, search, and interact with tweets

• User management (follow, mute, block)

• Lists, bookmarks, and spaces support

• Media upload (images/videos)

• Detailed rate limit handling

• Easy integration with AI assistants

🔑 Getting X API Credentials

To use this MCP server, you need X API credentials. Follow these steps:

Step 1: Create a Developer Account

1. Go to developer.x.com

2. Sign in with your X (Twitter) account

3. Click "Sign up for Free Account" (or apply for elevated access if needed)

4. Complete the developer agreement and verification

Step 2: Create a Project & App

1. Navigate to Developer Portal → Projects & Apps

2. Click "+ Add Project"

3. Name your project (e.g., "MCP Automation")

4. Select use case: "Exploring the API" or "Making a bot"

5. Click "+ Add App" within your project

6. Name your app (e.g., "X-MCP-Server")

Step 3: Generate API Keys

1. In your App settings, go to "Keys and Tokens"

2. Under Consumer Keys, click "Regenerate" to get:

   • API_KEY (API Key / Consumer Key)

   • API_SECRET (API Secret / Consumer Secret)

3. Under Authentication Tokens, generate:

   • ACCESS_TOKEN (Access Token)

   • ACCESS_TOKEN_SECRET (Access Token Secret)

4. Under Bearer Token, generate:

   • BEARER_TOKEN

Step 4: Enable App Permissions

1. Go to User authentication settings

2. Enable OAuth 1.0a

3. Set App permissions to "Read and Write"

4. Add a Callback URL (e.g., http://localhost:3000/callback)

5. Save changes

⚠️ Important: Keep your credentials secure! Never commit them to version control.

💻 Installation

Prerequisites

• Python 3.10+

• uv (recommended) or pip

Install with uv (Recommended)

# Clone the repository
git clone https://github.com/Lnxtanx/x-mcp-server.git
cd x-mcp-server

# Install dependencies
uv sync

Install with pip

# Clone the repository
git clone https://github.com/Lnxtanx/x-mcp-server.git
cd x-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install fastmcp tweepy python-dotenv

⚙️ Configuration

Step 1: Create Environment File

Copy the template and add your credentials:

cp .env.template .env

Step 2: Add Your Credentials

Edit .env with your X API credentials:

API_KEY=your_api_key_here
API_SECRET=your_api_secret_here
ACCESS_TOKEN=your_access_token_here
ACCESS_TOKEN_SECRET=your_access_token_secret_here
BEARER_TOKEN=your_bearer_token_here

🤖 Connecting to AI Clients

Claude Desktop

Add this configuration to your claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "x-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/path/to/x-mcp-server",
        "fastmcp",
        "run",
        "main.py"
      ]
    }
  }
}

Replace C:/path/to/x-mcp-server with your actual installation path.

After adding, restart Claude Desktop. You'll see the X API tools available in Claude.

ChatGPT / OpenAI

ChatGPT doesn't natively support MCP, but you can connect via:

Option 1: MCP Bridge/Proxy

Use an MCP-to-REST bridge to expose tools as API endpoints:

# Run MCP server with HTTP transport
uv run fastmcp dev main.py --transport http --port 8000

Then configure ChatGPT to call your endpoints via Custom GPT Actions or function calling.

Option 2: LangChain Integration

from langchain_openai import ChatOpenAI
from langchain_mcp import MCPClient

# Connect to local MCP server
mcp_client = MCPClient("http://localhost:8000")
tools = mcp_client.get_tools()

# Use with ChatGPT
llm = ChatOpenAI(model="gpt-4")
llm_with_tools = llm.bind_tools(tools)

Other MCP Clients

Running the Server Locally

# Development mode (with inspector)
uv run fastmcp dev main.py

# Production mode
uv run fastmcp run main.py

SSE Transport (for web clients)

uv run fastmcp run main.py --transport sse --port 8080

Stdio Transport (for CLI clients)

uv run fastmcp run main.py --transport stdio

🛠️ Available Tools (54 total)

Tweets

Engagement

Users

Lists & Media

⏱️ Rate Limits (Free Tier)

❌ Not Available in Free Tier

• Direct Messages

• Trends by WOEID

• User Search

• Full Archive Search

• Filtered Stream

📝 Tips for Free Tier

1. Cache responses – With 1 req/15 min limits, cache everything

2. Batch requests – Use multi-ID endpoints when possible

3. Use username lookup – Has 3 req/15 min (better than most)

4. Post sparingly – Only 17 tweets/day allowed

📄 License

This project is licensed under the VivekMind License.

Created by Lnxtanx

🤝 Contributing

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

📞 Support

• Issues: GitHub Issues

• Creator: @Lnxtanx