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

• Reply to tweets

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

2. Install dependencies:

3. Build the server:

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:

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

create_tweet

Create a new tweet.

Parameters:

• text (required): The text content of the tweet (max 280 characters)

Example:

reply_to_tweet

Reply to a tweet.

Parameters:

• tweet_id (required): The ID of the tweet to reply to

• text (required): The text content of the reply (max 280 characters)

Example:

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