A
securityA
licenseA
qualityA Model Context Protocol (MCP) server for managing social media posts, currently supporting X (formerly Twitter).
Last updated -
7
MIT License
Offers Docker-based deployment option for the X.com MCP server.
Provides recommended package management for installing and building the X.com MCP server.
Implements full TypeScript support with type safety for the X.com API integration.
Utilizes Zod validation for ensuring type safety in the X.com API interactions.
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:
"mcpServers": {
"x-com": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"X_COM_ACCESS_TOKEN": "your-access-token"
}
}
}
"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/tweetsManage Posts:
/2/tweets(POST),/2/tweets/:id(DELETE),/2/tweets/:id/hidden(PUT)Timelines:
/2/users/:id/tweets,/2/users/:id/mentionsSearch:
/2/tweets/search/recent,/2/tweets/search/allPost Counts:
/2/tweets/counts/recent,/2/tweets/counts/allRetweets:
/2/tweets/:id/retweets,/2/users/:id/retweetsLikes:
/2/tweets/:id/liking_users,/2/users/:id/liked_tweets,/2/users/:id/likesBookmarks:
/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.
This server cannot be installed
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that enables LLMs to interact with Salesforce data through SOQL queries, SOSL searches, and various API operations including record management.Last updated -10150MIT License
- -securityAlicense-qualityA Model Context Protocol server that allows LLMs to interact with web content through standardized tools, currently supporting web scraping functionality.Last updated -1MIT License
- -securityAlicense-qualityA Model Context Protocol server that enables AI models and applications to interact directly with Twitter/X, providing capabilities to create posts, reply to tweets, retrieve user data, and manage account actions.Last updated -611MIT License