X MCP Server
A Model Context Protocol (MCP) server for X (Twitter) integration that provides tools for reading your timeline and engaging with tweets. Designed for use with Claude desktop.
Features
- Get tweets from your home timeline
- Create new tweets with optional image attachments
- Reply to tweets with optional image attachments
- Delete tweets
- Image upload support (PNG, JPEG, GIF, WEBP)
- Built-in security validation and file size limits
- Built-in rate limit handling for the free API tier
- TypeScript implementation with full type safety
Prerequisites
- Node.js (v16 or higher)
- X (Twitter) Developer Account (Free)
- Claude desktop app
X API Access
X (Twitter) provides a free tier for basic API access:
Free Tier Features
- Post Limits:
- 500 posts per month at user level
- 500 posts per month at app level
- Read Limits:
- 100 reads per month
- Features:
- Access to v2 post posting endpoints
- Media upload endpoints
- Access to Ads API
- Limited to 1 app ID
- Login with X functionality
- Rate Limits:
- Rate-limited access to all endpoints
- Limits reset periodically
Note: For higher volume needs, paid tiers are available:
- Basic tier ($100/month): 50,000 tweets/month, additional endpoints
- Pro tier ($5000/month): Higher limits and enterprise features
You can access the free tier at: https://developer.x.com/en/portal/products/free
Installation
- Clone the repository:
git clone [your-repo-url]
cd x-mcp-server
- Install dependencies:
npm install
- Build the server:
npm run build
Configuration
You need to set up your X (Twitter) API credentials. Follow these detailed steps:
-
Go to the Twitter Developer Portal
- Sign in with your X (Twitter) account
- If you don't have a developer account, you'll be prompted to create one
-
Access the Free Tier:
- Visit https://developer.x.com/en/portal/products/free
- Click "Subscribe" for the Free Access tier
- Complete the registration process
-
Create a new project:
- Click "Create Project" button
- Enter a project name (e.g., "MCP Integration")
- Select "Free" as your setup
- Choose your use case
- Click "Next"
-
Create a new app within your project:
- Click "Create App"
- Enter an app name
- Click "Complete Setup"
-
Configure app settings:
- In your app dashboard, click "App Settings"
- Under "User authentication settings":
- Click "Set Up"
- Enable OAuth 1.0a
- Select "Web App" or "Native App"
- Enter any URL for callback (e.g., https://example.com/callback)
- Enter any URL for website (e.g., https://example.com)
- Click "Save"
-
Set app permissions:
- In app settings, find "App permissions"
- Change to "Read and Write"
- Click "Save"
-
Generate API Keys and Tokens:
- Go to "Keys and Tokens" tab
- Under "Consumer Keys":
- Click "View Keys" or "Regenerate"
- Save your API Key and API Key Secret
- Under "Access Token and Secret":
- Click "Generate"
- Make sure to select tokens with "Read and Write" permissions
- Save your Access Token and Access Token Secret
Important:
- Keep your keys and tokens secure and never share them publicly
- You'll need all four values:
- API Key (also called Consumer Key)
- API Key Secret (also called Consumer Secret)
- Access Token
- Access Token Secret
- Remember the free tier limits:
- 500 posts per month at user level
- 500 posts per month at app level
- 100 reads per month
Claude Desktop Configuration
To connect the X MCP server with Claude desktop, you need to configure it in the Claude settings. Follow these steps:
-
Open File Explorer
-
Navigate to the Claude config directory:
- Press Win + R
- Type
%APPDATA%/Claudeand press Enter - If the Claude folder doesn't exist, create it
-
Create or edit
claude_desktop_config.json:- If the file doesn't exist, create a new file named
claude_desktop_config.json - If it exists, open it in a text editor (like Notepad)
- If the file doesn't exist, create a new file named
-
Add the following configuration, replacing the placeholder values with your actual API credentials from the previous section:
{
"mcpServers": {
"x": {
"command": "node",
"args": ["%USERPROFILE%/Projects/MCP Basket/x-server/build/index.js"],
"env": {
"TWITTER_API_KEY": "paste-your-api-key-here",
"TWITTER_API_SECRET": "paste-your-api-key-secret-here",
"TWITTER_ACCESS_TOKEN": "paste-your-access-token-here",
"TWITTER_ACCESS_SECRET": "paste-your-access-token-secret-here"
}
}
}
}
- Save the file and restart Claude desktop
Note: Make sure to:
- Replace all four credential values with your actual API keys and tokens
- Keep the quotes ("") around each value
- Maintain the exact spacing and formatting shown above
- Save the file with the
.jsonextension
Available Tools
get_home_timeline
Get the most recent tweets from your home timeline.
Parameters:
limit(optional): Number of tweets to retrieve (default: 20, max: 100)
Example:
await use_mcp_tool({
server_name: "x",
tool_name: "get_home_timeline",
arguments: { limit: 5 }
});
create_tweet
Create a new tweet with optional image attachment.
Parameters:
text(required): The text content of the tweet (max 280 characters)image_path(optional): Absolute path to an image file (PNG, JPEG, GIF, WEBP, max 5MB)
Example (text-only):
await use_mcp_tool({
server_name: "x",
tool_name: "create_tweet",
arguments: { text: "Hello from MCP! 🤖" }
});
Example (with image):
await use_mcp_tool({
server_name: "x",
tool_name: "create_tweet",
arguments: {
text: "Check out this image! 📸",
image_path: "/path/to/image.png"
}
});
reply_to_tweet
Reply to a tweet with optional image attachment.
Parameters:
tweet_id(required): The ID of the tweet to reply totext(required): The text content of the reply (max 280 characters)image_path(optional): Absolute path to an image file (PNG, JPEG, GIF, WEBP, max 5MB)
Example (text-only):
await use_mcp_tool({
server_name: "x",
tool_name: "reply_to_tweet",
arguments: {
tweet_id: "1234567890",
text: "Great tweet! 👍"
}
});
Example (with image):
await use_mcp_tool({
server_name: "x",
tool_name: "reply_to_tweet",
arguments: {
tweet_id: "1234567890",
text: "Here's my response 📸",
image_path: "/path/to/image.jpg"
}
});
delete_tweet
Delete a tweet. Parameters:
tweet_id(required): The ID of the tweet to delete Example:
await use_mcp_tool({
server_name: "x",
tool_name: "delete_tweet",
arguments: {
tweet_id: "1234567890"
}
});
Development
npm run build: Build the TypeScript codenpm run dev: Run TypeScript in watch modenpm start: Start the MCP server
Rate Limiting
The server includes built-in rate limit handling for X's free tier:
- Monthly limits:
- 500 posts per month at user level
- 500 posts per month at app level
- 100 reads per month
- Features:
- Tracks monthly usage
- Provides exponential backoff for rate limit errors
- Clear error messages when limits are reached
- Automatic retry after rate limit window expires
License
MIT
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request