# 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](https://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](https://docs.x.com/x-api/posts/search/integrate/build-a-query) for more operators.
## Running
```bash
cd x-mcp
uv run python src/main.py
```
## License
MIT
