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

Tool	Description	Rate Limit
create_tweet	Post a new tweet	17/24h
delete_tweet	Delete a tweet	17/24h
get_tweet	Get tweet by ID	1/15min
get_tweets	Get multiple tweets	1/15min
search_recent_tweets	Search tweets (7 days)	1/15min
get_user_tweets	Get user's timeline	1/15min
get_user_mentions	Get mentions	1/15min
get_home_timeline	Get home feed	1/15min

Engagement

Tool	Description	Rate Limit
like_tweet / unlike_tweet	Like/unlike	1/15min
retweet / unretweet	Retweet/undo	1/15min
bookmark_tweet / remove_bookmark	Bookmark	1/15min

Users

Tool	Description	Rate Limit
get_me	Get authenticated user	25/24h
get_user_by_username	Lookup by handle	3/15min
follow_user / unfollow_user	Follow/unfollow	1/15min
mute_user / unmute_user	Mute/unmute	1/15min

Lists & Media

Tool	Description
create_list / delete_list / update_list	Manage lists
add_list_member / remove_list_member	List members
upload_media	Upload images/videos

---

⏱️ Rate Limits (Free Tier)

Operation	Limit
Create/Delete Tweet	17 requests / 24 hours
Get Authenticated User	25 requests / 24 hours
Lookup by Username	3 requests / 15 mins
Most Other Endpoints	1 request / 15 mins

❌ 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