x-mcp

A read-only X/Twitter MCP server using OAuth 2.0 App-Only (Bearer Token) authentication.

Features

• Read-only - No write operations, just data retrieval
• Bearer token auth - Uses app-only authentication, no user OAuth flow required
• 15 tools covering:
  • User lookup (by username, ID, or authenticated user)
  • Tweet lookup (by ID)
  • User timeline and mentions
  • Recent search (last 7 days)
  • Followers/following lists
  • Likes and retweets

Setup

1. Get an X API Bearer Token from developer.x.com
2. Configure the token in your Dedalus MCP client

Authentication Notes

This server uses OAuth 2.0 App-Only (Bearer Token) authentication, which:

• ✅ Works for public user/tweet lookups, search, followers, likes, retweets
• ❌ Does NOT work for /users/me (requires user context via OAuth 2.0 PKCE)

If you need user context (e.g., accessing private data or the authenticated user's profile), you'll need to implement OAuth 2.0 Authorization Code Flow with PKCE instead.

Available Tools

Users

• x_whoami - Get authenticated user profile
• x_get_user_by_username - Get user by username
• x_get_user - Get user by ID
• x_get_users - Get multiple users by ID

Tweets

• x_get_tweet - Get tweet by ID
• x_get_tweets - Get multiple tweets by ID
• x_get_user_tweets - Get a user's recent tweets
• x_get_user_mentions - Get tweets mentioning a user

Search

• x_search_recent - Search recent tweets (last 7 days)

Social Graph

• x_get_followers - Get a user's followers
• x_get_following - Get users a user follows

Engagement

• x_get_user_liked_tweets - Get tweets liked by a user
• x_get_liking_users - Get users who liked a tweet
• x_get_retweeted_by - Get users who retweeted a tweet

Search Query Examples

The x_search_recent tool supports X's search operators:

from:elonmusk              # Tweets from a user
#AI                        # Tweets with hashtag
machine learning -is:retweet   # Exclude retweets
python lang:en             # English tweets only
"exact phrase"             # Exact phrase match

See X API search docs for more operators.

Running

cd x-mcp
uv run python src/main.py

License

MIT