x-mcp

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

{
  "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 → 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)

npx @realaman90/x-mcp --setup

Or if running from source:

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

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

License

MIT