HosakaKeigo/x-mcp-server

X (Twitter) MCP Server

This is a Model Context Protocol (MCP) server for the X (formerly Twitter) API. From an MCP client such as Claude Desktop you can post tweets, read timelines, search posts, and more.

Features

This MCP server exposes the following tools:

• post_tweet: Post (publish) a tweet with optional image or video attachment
• get_home_timeline: Fetch the authenticated user's home timeline
• get_user_tweets: Fetch the latest tweets for a specific user
• search_tweets: Search tweets by keyword
• get_user_info: Fetch information for a specific user
• like_tweet: Like a tweet
• retweet: Retweet a tweet

Monthly limits:

• Read operations (get_home_timeline, get_user_tweets, search_tweets, get_user_info): Pro: 1,000,000 posts/month · Basic: 15,000 posts/month · Free: 100 posts/month
• Write operations (post_tweet, like_tweet, retweet): Pro: 300,000 posts/month · Basic: 50,000 posts/month · Free: 500 posts/month

※ Rate limits reference docs.x.com/x-api/fundamentals/rate-limits and X API pricing (retrieved on 8 Nov 2025) and may change as plans or API behavior evolve.

⚠️ Important Notice

X API specifications are subject to change. This server implementation is based on the X API v2 as documented at the time of development. Please refer to the official X API documentation for the most up-to-date API specifications, rate limits, and available endpoints.

Changes to the X API may affect:

• Available endpoints and their parameters
• Rate limits and pricing tiers
• Authentication requirements
• Response formats

Setup

1. Requirements

• Node.js 18.0.0 or newer
• X (Twitter) Developer account with API keys

2. Obtain API keys from the X Developer Portal

1. Visit the X Developer Portal
2. Create a new app or select an existing one
3. Collect the following credentials:
   • API Key (Consumer Key)
   • API Secret (Consumer Secret)
   • Access Token
   • Access Token Secret

3. Install dependencies

npm install

4. Configure environment variables

Copy .env.example to .env and fill in your keys:

cp .env.example .env

Edit .env:

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

5. Build

npm run build

Using with Claude Desktop

Quick Install (DXT/mcpb)

Pre-built packages are available from the Releases page. You can download the .mcpb file and install it directly in Claude Desktop.

1. Download the latest .mcpb file from Releases
2. In Claude Desktop, go to Settings → Extensions
3. Install the extension by one of these methods:
   • Double-click the downloaded .mcpb file, or
   • Drag and drop the file into Claude Desktop, or
   • Click "Install from file" in the Extensions settings
4. Configure your X API credentials in the extension settings:
   • X_API_KEY: Your API Key (Consumer Key)
   • X_API_SECRET: Your API Secret (Consumer Secret)
   • X_ACCESS_TOKEN: Your Access Token
   • X_ACCESS_TOKEN_SECRET: Your Access Token Secret

If you encounter errors:

• Verify that your API keys are correct (no extra spaces or quotes)
• Restart Claude Desktop completely
• Check the logs at:
  • macOS: ~/Library/Logs/Claude/mcp*.log
  • Windows: %APPDATA%\Claude\logs\mcp*.log

Manual Setup

1. Open the Claude Desktop config file

You can access the config file either through Claude Desktop settings or directly:

Via Claude Desktop:

• Go to Settings → Developers → Edit Config

Direct file paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the MCP server entry

Append the following configuration (adjust paths as needed):

macOS/Linux:

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/Users/username/path/to/x-mcp-server/dist/index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["C:\\Users\\username\\path\\to\\x-mcp-server\\dist\\index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

3. Restart Claude Desktop

Restart Claude Desktop completely so the settings take effect.

macOS:

• Choose "Quit Claude" from the menu
• Launch Claude Desktop again

Windows:

• Terminate Claude Desktop from Task Manager
• Launch Claude Desktop again

4. Verify the connection

After restarting, confirm that the tool icon (🔨) shows up in the bottom-left corner of the Claude input box.

Usage examples

Ask Claude Desktop things like:

"Fetch the latest 10 posts from my home timeline."

"Search for the latest 5 tweets about 'AI technology'."

"Get the latest tweets from @example_user."

"Show me the profile for @example_user."

"Post the tweet 'Hello, this is an MCP server test!'"

"Post a tweet with the text 'Check out this image!' and attach the image at /path/to/image.png"

"Post a tweet with the text 'My new video!' and attach the video at /path/to/video.mp4"

Troubleshooting

DXT/mcpb installation errors

If you encounter errors when using the DXT/mcpb package:

1. Verify API keys are correct

   • Double-check all four credentials (API Key, API Secret, Access Token, Access Token Secret)
   • Ensure there are no extra spaces or quotes in the configuration
   • Verify the keys are valid in the X Developer Portal

2. Restart Claude Desktop

   • Completely quit and restart Claude Desktop
   • macOS: Choose "Quit Claude" from the menu
   • Windows: Terminate Claude Desktop from Task Manager

3. Check logs for detailed errors

   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\mcp*.log

Claude Desktop does not detect the server

1. Fully restart Claude Desktop
2. Double-check for syntax errors in claude_desktop_config.json
3. Ensure the path to dist/index.js is correct (use absolute paths)
4. Check the logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\mcp*.log

API errors occur

1. Confirm that environment variables are set correctly
2. Verify that your X app has the required permissions (Read and Write)
3. Ensure the API keys are still valid

Test the server manually

# Run in development mode
npm run dev

# Or run the built output
npm run build
node dist/index.js

Development

Watch mode

npm run watch

In another terminal:

npm run dev

License

MIT