X.com MCP Server
A Model Context Protocol server that provides access to X.com's API capabilities. This server enables LLMs to interact with X.com (formerly Twitter) through OAuth 2.0 authentication, supporting all major Post-related operations including reading, writing, searching, and managing posts, likes, retweets, and bookmarks.
Features
- OAuth 2.0 Authentication - Secure Bearer token authentication
- Complete Post API Coverage - All X.com Post endpoints from the official API
- Type Safety - Full TypeScript implementation with Zod validation
- Comprehensive Tools - 21 tools covering all major X.com operations
Available Tools
Lookup
getSinglePost- Retrieve a single post by ID with optional field expansionsgetBulkPosts- Retrieve up to 100 posts by their IDs
Manage Posts
createPost- Create a new post with text, media, polls, replies, etc.deletePost- Delete a post by IDhideReply- Hide or unhide a reply to a post
Timelines
getUserTimeline- Get a user's timeline of postsgetUserMentions- Get posts that mention a specific user
Search
searchRecent- Search recent posts (last 7 days)searchAll- Search all posts (full archive - requires Academic/Enterprise access)
Post Counts
getPostCountsRecent- Get time-bucketed post counts for recent postsgetPostCountsAll- Get time-bucketed post counts for all posts (Academic/Enterprise)
Retweets
getRetweets- Get posts that retweet a specific postcreateRetweet- Retweet a postdeleteRetweet- Remove a retweet
Likes
getLikingUsers- Get users who liked a specific postgetLikedTweets- Get posts that a user has likedlikePost- Like a postunlikePost- Unlike a post
Bookmarks
getUserBookmarks- Get a user's bookmarked postsbookmarkPost- Bookmark a postremoveBookmark- Remove a bookmark
Installation
Using pnpm (recommended)
pnpm install
pnpm run build
After installation, you can run it using:
node dist/index.js
Using Docker
docker build -t x.com-mcp .
docker run -i --rm -e X_COM_ACCESS_TOKEN=your-access-token x.com-mcp
Configuration
Environment Variables
X_COM_ACCESS_TOKEN(required): Your X.com OAuth 2.0 access token
Authentication Setup
- Create an X.com Developer Account at developer.x.com
- Create a new project and app
- Generate OAuth 2.0 credentials
- Implement the OAuth 2.0 Authorization Code with PKCE flow
- Store the resulting access token as
X_COM_ACCESS_TOKEN
Configure for Claude.app
Add to your Claude settings:
Using pnpm
"mcpServers": {
"x-com": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"X_COM_ACCESS_TOKEN": "your-access-token"
}
}
}
Using Docker
"mcpServers": {
"x-com": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "X_COM_ACCESS_TOKEN=your-access-token", "x.com-mcp"]
}
}
Example Interactions
- Create a post:
{
"name": "createPost",
"arguments": {
"text": "Hello world! This is my first post via the MCP server.",
"reply_settings": "everyone"
}
}
- Search recent posts:
{
"name": "searchRecent",
"arguments": {
"query": "artificial intelligence",
"max_results": 10,
"tweet.fields": "created_at,author_id,public_metrics"
}
}
- Get user timeline:
{
"name": "getUserTimeline",
"arguments": {
"id": "123456789",
"max_results": 20,
"expansions": "author_id"
}
}
- Like a post:
{
"name": "likePost",
"arguments": {
"user_id": "123456789",
"tweet_id": "987654321"
}
}
- Get post counts:
{
"name": "getPostCountsRecent",
"arguments": {
"query": "machine learning",
"granularity": "day"
}
}
API Endpoints Covered
This server implements all Post-related endpoints from the X.com API v2 specification:
- Lookup:
/2/tweets/:id,/2/tweets - Manage Posts:
/2/tweets(POST),/2/tweets/:id(DELETE),/2/tweets/:id/hidden(PUT) - Timelines:
/2/users/:id/tweets,/2/users/:id/mentions - Search:
/2/tweets/search/recent,/2/tweets/search/all - Post Counts:
/2/tweets/counts/recent,/2/tweets/counts/all - Retweets:
/2/tweets/:id/retweets,/2/users/:id/retweets - Likes:
/2/tweets/:id/liking_users,/2/users/:id/liked_tweets,/2/users/:id/likes - Bookmarks:
/2/users/:id/bookmarks
Required Scopes
Ensure your X.com app has the following OAuth 2.0 scopes:
tweet.read- Read posts and user informationtweet.write- Create and delete poststweet.moderate.write- Hide/unhide repliesusers.read- Read user informationlike.read- Read likes informationlike.write- Like and unlike postsbookmark.read- Read bookmarksbookmark.write- Create and delete bookmarks
Debugging
You can use the MCP inspector to debug the server:
npx @modelcontextprotocol/inspector node dist/index.js
Examples of Questions for Claude
- "Can you search for recent posts about artificial intelligence?"
- "Create a post about the benefits of TypeScript."
- "Find posts that mention machine learning and show their engagement metrics."
- "Get my recent bookmarks and analyze the topics."
Build
# Install dependencies
pnpm install
# Build TypeScript
pnpm run build
# Start server
pnpm start
Rate Limits
Be aware of X.com API rate limits:
- Most read operations: 300 requests per 15 minutes
- Write operations: 50 requests per 15 minutes
- Bookmark operations: 50 write / 180 read per 15 minutes
Refer to the X.com API documentation for detailed rate limit information.