# X-MCP 2.0

MCP server for the **X/Twitter API v2** with **OAuth 2.0 PKCE** authentication.

> Use Claude to post tweets, search X, like, retweet, and more — with modern OAuth 2.0.

## Why 2.0?

The original [twitter-mcp](https://github.com/EnesCinr/twitter-mcp) uses OAuth 1.0a, which requires 4 separate keys and doesn't support newer API features. X-MCP 2.0 uses **OAuth 2.0 with PKCE**, the recommended auth method for Twitter API v2.

| Feature | twitter-mcp | X-MCP 2.0 |
|---------|-------------|-----------|
| Auth | OAuth 1.0a (4 keys) | OAuth 2.0 PKCE (modern) |
| Token refresh | No | Auto-refresh |
| Post tweet | Yes | Yes |
| Search | Yes | Yes |
| Get tweet | No | Yes |
| User profile | No | Yes |
| Home timeline | No | Yes |
| Like | No | Yes |
| Retweet | No | Yes |
| Reply | No | Yes |
| User tweets | No | Yes |
| MCP SDK | 0.6.0 | 1.x |

## Tools (10)

| Tool | Description |
|------|-------------|
| `post_tweet` | Post a tweet (supports replies & quote tweets) |
| `search_tweets` | Search tweets by query |
| `get_tweet` | Get a specific tweet by ID |
| `get_my_profile` | Get your profile info |
| `get_user` | Get any user's profile by username |
| `get_timeline` | Get your home timeline |
| `like_tweet` | Like a tweet |
| `retweet` | Retweet a tweet |
| `reply_to_tweet` | Reply to a tweet |
| `get_user_tweets` | Get recent tweets from a user |

## Setup

### 1. Get Twitter API Credentials

1. Go to [developer.x.com](https://developer.x.com) and create an app
2. Under **Keys and Tokens**, find **OAuth 2.0 Client ID and Client Secret**
3. Under **User authentication settings**, click **Set up**:
   - App permissions: **Read and write**
   - Type of App: **Web App, Automated App or Bot**
   - Callback URI: `http://127.0.0.1:8739/callback`
   - Website URL: your website or GitHub profile

### 2. Authorize (One-Time)

```bash
git clone https://github.com/JFan5/X-MCP-2.0.git
cd X-MCP-2.0
npm install

# Run the auth flow — opens browser for Twitter login
CLIENT_ID=your_client_id CLIENT_SECRET=your_client_secret npm run auth
```

This saves tokens to `~/.x-mcp-tokens.json` and prints the `ACCESS_TOKEN` and `REFRESH_TOKEN`.

### 3. Configure Claude

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": ["/path/to/X-MCP-2.0/dist/index.js"],
      "env": {
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret",
        "ACCESS_TOKEN": "your_access_token",
        "REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

Or for **Claude Code**, add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": ["/path/to/X-MCP-2.0/dist/index.js"],
      "env": {
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret",
        "ACCESS_TOKEN": "your_access_token",
        "REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

### 4. Build (if running from source)

```bash
npm run build
```

## Token Refresh

If you included the `REFRESH_TOKEN`, X-MCP 2.0 automatically refreshes your access token when it expires (every 2 hours). No manual intervention needed.

## Examples

Ask Claude:

- *"Post a tweet about my new open-source project"*
- *"Search for tweets about GRPO reinforcement learning"*
- *"What's on my Twitter timeline?"*
- *"Like the top tweet about machine learning"*
- *"Show me @kaboroevich's recent tweets"*

## License

MIT