# X MCP Server 🐦

[![License: VivekMind](https://img.shields.io/badge/License-VivekMind-blue.svg)](./LICENSE)

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](#-features)
- [Getting X API Credentials](#-getting-x-api-credentials)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Connecting to AI Clients](#-connecting-to-ai-clients)
  - [Claude Desktop](#claude-desktop)
  - [ChatGPT / OpenAI](#chatgpt--openai)
  - [Other MCP Clients](#other-mcp-clients)
- [Available Tools](#-available-tools)
- [Rate Limits](#-rate-limits)
- [License](#-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](https://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](https://github.com/astral-sh/uv) (recommended) or pip

### Install with uv (Recommended)

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

# Install dependencies
uv sync
```

### Install with pip

```bash
# 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:

```bash
cp .env.template .env
```

### Step 2: Add Your Credentials

Edit `.env` with your X API credentials:

```env
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`

```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:

```bash
# 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

```python
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

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

# Production mode
uv run fastmcp run main.py
```

#### SSE Transport (for web clients)

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

#### Stdio Transport (for CLI clients)

```bash
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](https://github.com/Lnxtanx)

---

## 🤝 Contributing

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

---

## 📞 Support

- **Issues:** [GitHub Issues](https://github.com/Lnxtanx/x-mcp-server/issues)
- **Creator:** [@Lnxtanx](https://github.com/Lnxtanx)