📌Overview

Purpose: To provide a Model Context Protocol (MCP) server for X (Twitter) integration, enabling users to read their timeline and engage with tweets seamlessly.

Overview: The X MCP Server is designed specifically for integration with Claude desktop, facilitating interactions with the X (Twitter) API. It allows for real-time access to timelines and tweet management while ensuring type safety through TypeScript implementation.

Key Features:

Get Tweets from Home Timeline: Enables users to easily retrieve the most recent tweets from their timeline, enhancing engagement with their social media content.
Create and Reply to Tweets: Offers functionalities to post new tweets and respond to existing ones, allowing users to actively participate in conversations on the platform.
Built-in Rate Limit Handling: Automatically manages API rate limits for the free tier, ensuring users receive clear feedback on usage and preventing service disruptions due to exceeding limits.
TypeScript Implementation: Provides full type safety, reducing the likelihood of runtime errors and improving developer experience.

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

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

Set up your X (Twitter) API credentials:

Go to the Twitter Developer Portal (https://developer.twitter.com/en/portal/dashboard)
- Sign in with your X (Twitter) account
- If you don't have a developer account, create one
Access the Free Tier:
- Visit https://developer.x.com/en/portal/products/free
- Click "Subscribe" for the Free Access tier
- Complete registration
Create a new project:
- Click "Create Project"
- Enter a project name (e.g. "MCP Integration")
- Select "Free" as 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 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 and website (e.g., https://example.com/callback)
  - Click "Save"
Set app permissions:
- Change "App permissions" to "Read and Write"
- Click "Save"
Generate API Keys and Tokens:
- In "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"
    - Select tokens with "Read and Write" permissions
    - Save your Access Token and Access Token Secret

Important:

Keep your keys and tokens secure.
You need these four values:
- API Key (Consumer Key)
- API Key Secret (Consumer Secret)
- Access Token
- Access Token Secret
Remember free tier limits:
- 500 posts per month at user and app level
- 100 reads per month

Claude Desktop Configuration

To connect the X MCP server with Claude desktop:

Open File Explorer
Navigate to the Claude config directory:
- Press Win + R
- Type %APPDATA%/Claude and Enter
- If folder does not exist, create it
Create or edit claude_desktop_config.json:
- Create if missing or open in text editor
Add the following configuration, replacing placeholder values with your API credentials:

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

Make sure to preserve the formatting and use .json extension.

Available Tools

get_home_timeline

Gets the most recent tweets from your home timeline.
Parameters:

limit (optional): Number of tweets (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): Text content (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): ID of tweet to reply to
text (required): Reply text (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 on limit reach
- 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