X MCP Server

View original on GitHub

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

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%/Claude and 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)
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 .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

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