npm package: @realaman90/x-mcp
Description: MCP server for X/Twitter API — read tweets, profiles, timelines + write posts, likes, retweets, follows, bookmarks, and more
Latest version: 2.1.0

# x-mcp

[![npm version](https://img.shields.io/npm/v/@realaman90/x-mcp)](https://www.npmjs.com/package/@realaman90/x-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

MCP server for X/Twitter API — give Claude (or any MCP client) the ability to search, read, post, like, retweet, follow, bookmark, manage lists, explore communities, and more.

**44 tools total**: 17 read-only (Bearer token) + 27 write/advanced-read (OAuth 1.0a).

## Why

- Search and analyze tweets without leaving your AI workflow
- Post, reply, quote-tweet, and run polls directly from Claude
- Like, retweet, follow, bookmark, block, mute — all from your terminal
- Manage X Lists — create, update, add/remove members, pin/unpin
- Explore Communities, trending topics, and news
- Upload images and attach them to tweets
- Monitor your API usage
- Works with Claude Code, Claude Desktop, Codex, or any MCP client
- OAuth credentials optional — runs read-only with just a Bearer token

## Tools

### Always available (Bearer token only) — 17 tools

| Tool | Description |
|------|-------------|
| **Tweets** | |
| `search_tweets` | Search recent tweets (last 7 days) with full query operators |
| `get_user_profile` | Get user profile by username (bio, followers, etc.) |
| `get_user_tweets` | Get a user's recent tweets by user ID |
| `get_tweet_replies` | Get replies to a specific tweet |
| `get_tweet` | Get a single tweet with full details and metrics |
| **Users** | |
| `get_user_followers` | Get a user's followers |
| `get_user_following` | Get who a user is following |
| `get_liking_users` | Get users who liked a tweet |
| **Trends** | |
| `get_trending_topics` | Get trending topics by location (WOEID) |
| **Communities** | |
| `get_community` | Get details for a specific community |
| `search_communities` | Search communities by keyword |
| **News** | |
| `get_news` | Get a news article/cluster by ID |
| **Usage** | |
| `get_api_usage` | Get your API tweet consumption stats |
| **Lists** | |
| `get_list` | Get list details by ID |
| `get_user_lists` | Get lists owned by a user |
| `get_list_members` | Get members of a list |
| `get_user_list_memberships` | Get lists a user belongs to |

### Requires OAuth 1.0a — 27 tools (auto-registered when credentials present)

| Tool | Description |
|------|-------------|
| **Read** | |
| `get_my_profile` | Get your own profile |
| `get_user_mentions` | Get tweets mentioning a user |
| `get_quote_tweets` | Get quote tweets of a tweet |
| `get_bookmarks` | Get your bookmarked tweets |
| **Post** | |
| `upload_media` | Upload an image (from URL) for use in tweets |
| `create_post` | Post a tweet (text, reply, quote, poll, media) |
| `delete_post` | Delete your own tweet |
| **Engage** | |
| `like_post` / `unlike_post` | Like or unlike a tweet |
| `repost` / `unrepost` | Retweet or undo retweet |
| `follow_user` / `unfollow_user` | Follow or unfollow a user |
| `bookmark_post` / `unbookmark_post` | Bookmark or remove bookmark |
| `block_user` / `unblock_user` | Block or unblock a user |
| `mute_user` / `unmute_user` | Mute or unmute a user |
| **Lists** | |
| `create_list` | Create a new list |
| `update_list` | Update list name/description/privacy |
| `delete_list` | Delete a list you own |
| `add_list_member` | Add a user to your list |
| `remove_list_member` | Remove a user from your list |
| `pin_list` / `unpin_list` | Pin or unpin a list |

## Quick Start

### 1. Get X API credentials

1. Go to [developer.x.com](https://developer.x.com) → **Developer Portal** → **Projects & Apps**
2. Create a **Project** and an **App** inside it
3. Go to **Keys and Tokens**:
   - Copy the **Bearer Token** (required)
   - Copy the **API Key** and **API Secret** (for write access)
   - Generate and copy the **Access Token** and **Access Token Secret** (for write access)

> **Read-only mode**: Only the Bearer Token is required. The 17 read tools work without OAuth.

### 2. Add to Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "x": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@realaman90/x-mcp"],
      "env": {
        "X_BEARER_TOKEN": "your-bearer-token",
        "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"
      }
    }
  }
}
```

Or add to **Claude Desktop**: **Settings** → **Developer** → **Edit Config** → same block.

> Omit the `X_API_KEY`/`X_API_SECRET`/`X_ACCESS_TOKEN`/`X_ACCESS_TOKEN_SECRET` lines for read-only mode.

### 3. Restart Claude and test

```
Search X for "AI agents" in English, no retweets
```

```
Post a tweet: "Hello from Claude!"
```

## Team Setup (sharing your app with others)

If you want a team member to use your X app but post from **their own account**:

### App owner (one-time)

1. In [X Developer Portal](https://developer.x.com) → your app → **Authentication Settings**:
   - App permissions: **Read and write**
   - Type of App: **Web App, Automated App or Bot**
   - Callback URL: `http://localhost:3456/callback`
2. Share your **API Key**, **API Secret**, and **Bearer Token** with them

### Team member (one-time)

```bash
npx @realaman90/x-mcp --setup
```

Or if running from source:

```bash
X_API_KEY=<app_api_key> X_API_SECRET=<app_api_secret> node setup.js
```

This will:
1. Open your browser to X's authorization page
2. You log in with **your** X account and click "Authorize"
3. Print your personal **Access Token** and **Access Token Secret**
4. Add those to your Claude config — done. Tokens never expire.

## Usage Examples

### Search tweets
```
"AI video" lang:en -is:retweet           # English tweets about AI video
from:elonmusk has:media                   # Elon's tweets with media
#buildinpublic -is:reply                  # Hashtag, original tweets only
```

### Post and engage
```
Post a tweet: "Shipping a new feature today 🚀"
Reply to tweet 1234567890 saying "Great thread!"
Like tweet 1234567890
Retweet the latest tweet from @username
```

### Lists
```
Create a private list called "AI Builders"
Add @username to my "AI Builders" list
Show me the members of list 123456
```

### Chain tools
1. `get_user_profile` → get user ID from username
2. `get_user_tweets` → get their recent tweets
3. `like_post` → like a specific tweet
4. `create_post` → reply to it

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `X_BEARER_TOKEN` | Yes | Bearer token for read-only API access |
| `X_API_KEY` | For write | OAuth 1.0a consumer key (API Key) |
| `X_API_SECRET` | For write | OAuth 1.0a consumer secret (API Secret) |
| `X_ACCESS_TOKEN` | For write | OAuth 1.0a access token (per-user) |
| `X_ACCESS_TOKEN_SECRET` | For write | OAuth 1.0a access token secret (per-user) |

## Requirements

- **Node.js 18+** (for native `fetch`)
- **X API access** — [Get it here](https://developer.x.com)

## How It Works

Single-file MCP server (~720 lines). No build step, no config files, zero extra dependencies. Uses Node.js built-in `crypto` for OAuth signing.

```
Claude ↔ stdio ↔ x-mcp ↔ X API v2
                    ↑
          Bearer (read) + OAuth 1.0a (write)
```

## Contributing

Contributions welcome! Feel free to open issues or submit PRs.

1. Fork the repo
2. Create your branch (`git checkout -b feature/my-feature`)
3. Commit your changes
4. Push and open a Pull Request

## Author

Built by [@amanrawatamg](https://x.com/amanrawatamg)

## License

MIT