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

1. Clone the repository:

git clone [your-repo-url]
cd x-mcp-server

1. Install dependencies:

npm install

1. Build the server:

npm run build

Configuration

You need to set up your X (Twitter) API credentials. Follow these detailed steps:

1. 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

2. Access the Free Tier:

   • Visit https://developer.x.com/en/portal/products/free
   • Click "Subscribe" for the Free Access tier
   • Complete the registration process

3. 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"

4. Create a new app within your project:

   • Click "Create App"
   • Enter an app name
   • Click "Complete Setup"

5. 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"

6. Set app permissions:

   • In app settings, find "App permissions"
   • Change to "Read and Write"
   • Click "Save"

7. 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:

1. Open File Explorer

2. Navigate to the Claude config directory:

   • Press Win + R
   • Type %APPDATA%/Claude and press Enter
   • If the Claude folder doesn't exist, create it

3. 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)

4. 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"
      }
    }
  }
}

1. 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 .json extension

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 to
• text (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 code
• npm run dev: Run TypeScript in watch mode
• npm 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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request