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:

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

2. Install dependencies:

   npm install

3. 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
2. Sign in with your X (Twitter) account

3. If you Do not have a developer account, you'll be prompted to create one

4. Access the Free Tier:

5. Visit https://developer.x.com/en/portal/products/free
6. Click "Subscribe" for the Free Access tier

7. Complete the registration process

8. Create a new project:

9. Click "Create Project" button
10. Enter a project name (e.g., "MCP Integration")
11. Select "Free" as your setup
12. Choose your use case

13. Click "Next"

14. Create a new app within your project:

15. Click "Create App"
16. Enter an app name

17. Click "Complete Setup"

18. Configure app settings:

19. In your app dashboard, click "App Settings"

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

21. Set app permissions:

22. In app settings, find "App permissions"
23. Change to "Read and Write"

24. Click "Save"

25. Generate API Keys and Tokens:

26. Go to "Keys and Tokens" tab
27. Under "Consumer Keys":
    • Click "View Keys" or "Regenerate"
    • Save your API Key and API Key Secret
28. 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:
3. Press Win + R
4. Type %APPDATA%/Claude and press Enter

5. If the Claude folder does not exist, create it

6. Create or edit claude_desktop_config.json:

7. If the file does not exist, create a new file named claude_desktop_config.json

8. If it exists, open it in a text editor (like Notepad)

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

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

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

Example:

await use_mcp_tool({
  server_name: "x",
  tool_name: "create_tweet",
  arguments: { text: "Hello from MCP! ?" }
});

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:

await use_mcp_tool({
  server_name: "x",
  tool_name: "reply_to_tweet",
  arguments: {
    tweet_id: "1234567890",
    text: "Great tweet! ?"
  }
});

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