# X (Twitter) MCP Server

This is a Model Context Protocol (MCP) server for the X (formerly Twitter) API. From an MCP client such as Claude Desktop you can post tweets, read timelines, search posts, and more.

## Features

This MCP server exposes the following tools:

- **post_tweet**: Post (publish) a tweet with optional image or video attachment
- **get_home_timeline**: Fetch the authenticated user's home timeline
- **get_user_tweets**: Fetch the latest tweets for a specific user
- **search_tweets**: Search tweets by keyword
- **get_user_info**: Fetch information for a specific user
- **like_tweet**: Like a tweet
- **retweet**: Retweet a tweet

| Tool | Description | Key rate limits (Pro / Basic / Free) |
| --- | --- | --- |
| `post_tweet` | Create a new tweet with text and optional image (max 5MB: PNG, JPEG, GIF, WEBP) or video (max 512MB: MP4, MOV, AVI, WEBM, M4V) | Pro: 100 req/15 min (per user) · 10,000 req/24 h (per app)<br>Basic: 100 req/24 h (per user) · 1,667 req/24 h (per app)<br>Free: 17 req/24 h (per user/app) |
| `get_home_timeline` | Retrieve a configurable number of posts from the authenticated home timeline | Pro: 180 req/15 min (per user)<br>Basic: 5 req/15 min (per user)<br>Free: 1 req/15 min (per user) |
| `get_user_tweets` | Retrieve the latest tweets for a given username (without @) | Pro: 900 req/15 min (per user) · 1,500 req/15 min (per app)<br>Basic: 5 req/15 min (per user) · 10 req/15 min (per app)<br>Free: 1 req/15 min (per user/app) |
| `search_tweets` | Search recent tweets by keyword | Pro: 300 req/15 min (per user) · 450 req/15 min (per app)<br>Basic: 60 req/15 min (per user/app)<br>Free: 1 req/15 min (per user/app) |
| `get_user_info` | Fetch profile information for a given username | Pro: 900 req/15 min (per user) · 300 req/15 min (per app)<br>Basic: 100 req/24 h (per user) · 500 req/24 h (per app)<br>Free: 3 req/15 min (per user/app) |
| `like_tweet` | Like a tweet by ID | Pro: 1,000 req/24 h (per user)<br>Basic: 200 req/24 h (per user)<br>Free: 1 req/15 min (per user) |
| `retweet` | Retweet a tweet by ID | Pro: 50 req/15 min (per user)<br>Basic: 5 req/15 min (per user)<br>Free: 1 req/15 min (per user) |

**Monthly limits:**
- **Read operations** (get_home_timeline, get_user_tweets, search_tweets, get_user_info): Pro: 1,000,000 posts/month · Basic: 15,000 posts/month · Free: 100 posts/month
- **Write operations** (post_tweet, like_tweet, retweet): Pro: 300,000 posts/month · Basic: 50,000 posts/month · Free: 500 posts/month

※ Rate limits reference [docs.x.com/x-api/fundamentals/rate-limits](https://docs.x.com/x-api/fundamentals/rate-limits) and [X API pricing](https://developer.x.com/en/portal/products) (retrieved on 8 Nov 2025) and may change as plans or API behavior evolve.

## ⚠️ Important Notice

**X API specifications are subject to change.** This server implementation is based on the X API v2 as documented at the time of development. Please refer to the [official X API documentation](https://docs.x.com/x-api/introduction) for the most up-to-date API specifications, rate limits, and available endpoints.

Changes to the X API may affect:
- Available endpoints and their parameters
- Rate limits and pricing tiers
- Authentication requirements
- Response formats

## Setup

### 1. Requirements

- Node.js 18.0.0 or newer
- X (Twitter) Developer account with API keys

### 2. Obtain API keys from the X Developer Portal

1. Visit the [X Developer Portal](https://developer.x.com/en/portal/dashboard)
2. Create a new app or select an existing one
3. Collect the following credentials:
   - API Key (Consumer Key)
   - API Secret (Consumer Secret)
   - Access Token
   - Access Token Secret

### 3. Install dependencies

```bash
npm install
```

### 4. Configure environment variables

Copy `.env.example` to `.env` and fill in your keys:

```bash
cp .env.example .env
```

Edit `.env`:

```env
X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
```

### 5. Build

```bash
npm run build
```

## Using with Claude Desktop

### Quick Install (DXT/mcpb)

Pre-built packages are available from the [Releases](https://github.com/HosakaKeigo/x-mcp-server/releases) page. You can download the `.mcpb` file and install it directly in Claude Desktop.

1. Download the latest `.mcpb` file from [Releases](https://github.com/HosakaKeigo/x-mcp-server/releases)
2. In Claude Desktop, go to **Settings → Extensions**
3. Install the extension by one of these methods:
   - Double-click the downloaded `.mcpb` file, or
   - Drag and drop the file into Claude Desktop, or
   - Click "Install from file" in the Extensions settings
4. Configure your X API credentials in the extension settings:
   - `X_API_KEY`: Your API Key (Consumer Key)
   - `X_API_SECRET`: Your API Secret (Consumer Secret)
   - `X_ACCESS_TOKEN`: Your Access Token
   - `X_ACCESS_TOKEN_SECRET`: Your Access Token Secret

**If you encounter errors:**
- Verify that your API keys are correct (no extra spaces or quotes)
- Restart Claude Desktop completely
- Check the logs at:
  - **macOS:** `~/Library/Logs/Claude/mcp*.log`
  - **Windows:** `%APPDATA%\Claude\logs\mcp*.log`

### Manual Setup

#### 1. Open the Claude Desktop config file

You can access the config file either through Claude Desktop settings or directly:

**Via Claude Desktop:**
- Go to **Settings → Developers → Edit Config**

**Direct file paths:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

#### 2. Add the MCP server entry

Append the following configuration (adjust paths as needed):

**macOS/Linux:**
```json
{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/Users/username/path/to/x-mcp-server/dist/index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["C:\\Users\\username\\path\\to\\x-mcp-server\\dist\\index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}
```

#### 3. Restart Claude Desktop

Restart Claude Desktop completely so the settings take effect.

**macOS:**
- Choose "Quit Claude" from the menu
- Launch Claude Desktop again

**Windows:**
- Terminate Claude Desktop from Task Manager
- Launch Claude Desktop again

#### 4. Verify the connection

After restarting, confirm that the tool icon (🔨) shows up in the bottom-left corner of the Claude input box.

## Usage examples

Ask Claude Desktop things like:

```
"Fetch the latest 10 posts from my home timeline."

"Search for the latest 5 tweets about 'AI technology'."

"Get the latest tweets from @example_user."

"Show me the profile for @example_user."

"Post the tweet 'Hello, this is an MCP server test!'"

"Post a tweet with the text 'Check out this image!' and attach the image at /path/to/image.png"

"Post a tweet with the text 'My new video!' and attach the video at /path/to/video.mp4"
```

## Troubleshooting

### DXT/mcpb installation errors

If you encounter errors when using the DXT/mcpb package:

1. **Verify API keys are correct**
   - Double-check all four credentials (API Key, API Secret, Access Token, Access Token Secret)
   - Ensure there are no extra spaces or quotes in the configuration
   - Verify the keys are valid in the [X Developer Portal](https://developer.x.com/en/portal/dashboard)

2. **Restart Claude Desktop**
   - Completely quit and restart Claude Desktop
   - **macOS:** Choose "Quit Claude" from the menu
   - **Windows:** Terminate Claude Desktop from Task Manager

3. **Check logs for detailed errors**
   - **macOS:** `~/Library/Logs/Claude/mcp*.log`
   - **Windows:** `%APPDATA%\Claude\logs\mcp*.log`

### Claude Desktop does not detect the server

1. Fully restart Claude Desktop
2. Double-check for syntax errors in `claude_desktop_config.json`
3. Ensure the path to `dist/index.js` is correct (use absolute paths)
4. Check the logs:
   - **macOS:** `~/Library/Logs/Claude/mcp*.log`
   - **Windows:** `%APPDATA%\Claude\logs\mcp*.log`

### API errors occur

1. Confirm that environment variables are set correctly
2. Verify that your X app has the required permissions (Read and Write)
3. Ensure the API keys are still valid

### Test the server manually

```bash
# Run in development mode
npm run dev

# Or run the built output
npm run build
node dist/index.js
```

## Development

### Watch mode

```bash
npm run watch
```

In another terminal:

```bash
npm run dev
```

## License

MIT