MCP Twitter/X Server

A Model Context Protocol (MCP) server that provides integration with Twitter/X, allowing you to read posts from users and create new posts.

Features

• Read Posts: Fetch the latest tweets from any public Twitter/X user
• Create Posts: Post new tweets to your Twitter/X account
• Get Specific Post: Retrieve a specific tweet by its ID
• Search Posts: Search for tweets matching a query
• Configurable Options: Control tweet count, include/exclude replies and retweets

Available Tools

1. read_posts

Fetch the latest posts from a specified Twitter/X user.

Parameters:

• username (required): The Twitter/X username (without @)
• count (optional): Number of tweets to fetch (1-100, default: 20)
• includeReplies (optional): Whether to include replies (default: false)
• includeRetweets (optional): Whether to include retweets (default: true)

Example:

{
  "username": "elonmusk",
  "count": 10,
  "includeReplies": false,
  "includeRetweets": true
}

2. create_post

Create a new post on Twitter/X.

Parameters:

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

Example:

{
  "text": "Hello, world! This is my first tweet via MCP."
}

3. get_post

Get a specific tweet by ID.

Parameters:

• tweetId (required): The ID of the tweet to retrieve

Example:

{
  "tweetId": "1234567890123456789"
}

4. search_posts

Search for tweets matching a query.

Parameters:

• query (required): The search query
• count (optional): Number of tweets to fetch (1-100, default: 10)
• resultType (optional): "recent" or "popular" (default: "recent")

Example:

{
  "query": "AI and machine learning",
  "count": 15,
  "resultType": "popular"
}

Setup

1. Prerequisites

• Node.js 18 or higher
• Twitter Developer Account with API access

2. Twitter API Setup

1. Go to the Twitter Developer Portal

2. Create a new app or use an existing one

3. Generate the following credentials:

   • API Key
   • API Secret
   • Access Token
   • Access Token Secret
   • Bearer Token

4. Make sure your app has the following permissions:

   • Read and Write (for creating posts)
   • Users and Tweets (for reading posts)

3. Installation

Option A: Local Installation

1. Clone or download this repository

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Set up environment variables:

   cp .env.example .env
   

Option B: Docker Installation

1. Clone or download this repository

2. Set up environment variables:

   cp .env.example .env
   

3. Build and run with Docker:

   docker build -t mcp-twitter-x-server .
   docker run -it --env-file .env mcp-twitter-x-server
   

   Or use Docker Compose:

   docker-compose up --build
   

4. Edit .env and add your Twitter API credentials:

   TWITTER_API_KEY=your_api_key_here
   TWITTER_API_SECRET=your_api_secret_here
   TWITTER_ACCESS_TOKEN=your_access_token_here
   TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   TWITTER_BEARER_TOKEN=your_bearer_token_here
   

4. Configuration for MCP Clients

Add the server to your MCP client configuration. For example, in Claude Desktop:

{
  "mcpServers": {
    "mcp-twitter-x-server": {
      "command": "node",
      "args": ["/path/to/MCP-X/dist/index.js"],
      "env": {
        "TWITTER_API_KEY": "your_api_key_here",
        "TWITTER_API_SECRET": "your_api_secret_here",
        "TWITTER_ACCESS_TOKEN": "your_access_token_here",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret_here",
        "TWITTER_BEARER_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

Usage Examples

Reading Posts

# Get latest 5 tweets from @elonmusk (excluding replies)
{
  "tool": "read_posts",
  "arguments": {
    "username": "elonmusk",
    "count": 5,
    "includeReplies": false
  }
}

Creating a Post

# Post a new tweet
{
  "tool": "create_post", 
  "arguments": {
    "text": "Just set up my MCP Twitter server! 🚀 #MCP #TwitterAPI"
  }
}

Searching Posts

# Search for recent tweets about AI
{
  "tool": "search_posts",
  "arguments": {
    "query": "artificial intelligence",
    "count": 10,
    "resultType": "recent"
  }
}

Response Format

Tweet Object Structure

{
  "id": "1234567890123456789",
  "text": "This is a tweet",
  "author": {
    "username": "example_user",
    "name": "Example User",
    "id": "987654321"
  },
  "created_at": "2023-10-01T12:00:00.000Z",
  "metrics": {
    "likes": 42,
    "retweets": 7,
    "replies": 3,
    "quotes": 1
  },
  "url": "https://twitter.com/example_user/status/1234567890123456789"
}

Development

Scripts

• npm run build - Build the TypeScript project
• npm run start - Start the server
• npm run dev - Development mode with auto-restart
• npm run clean - Clean build artifacts

Project Structure

src/
├── index.ts              # Main MCP server
├── twitter-client.ts     # Twitter API v2 wrapper
├── twitter-client-v1.ts  # Twitter API v1.1 fallback
dist/                     # Compiled JavaScript
mcp-config.json           # Sample MCP configuration
.env.example              # Environment variables template

Error Handling

The server includes comprehensive error handling for:

• Invalid Twitter API credentials
• Rate limiting
• User not found
• Tweet not found
• Invalid parameters
• Network errors

All errors are returned in a structured format:

{
  "success": false,
  "error": "Detailed error message"
}

Rate Limiting

The Twitter API has rate limits. The server will throw errors when limits are exceeded. Consider implementing caching or request throttling for production use.

Security Notes

• Never commit your .env file with real credentials
• Use environment variables for all sensitive configuration
• Consider implementing additional authentication for production deployments
• Monitor your Twitter API usage to avoid unexpected charges

License

MIT License - see LICENSE file for details.

Docker MCP Registry

This server is designed to be compatible with the Docker MCP Registry. The repository includes:

• Dockerfile - Container configuration for production deployment
• docker-compose.yml - Easy local testing with Docker
• tools.json - Tool definitions for the Docker MCP Registry
• .dockerignore - Optimized Docker build context

Using with Docker MCP Toolkit

This server can be easily installed and managed through Docker Desktop's MCP Toolkit once it's available in the Docker MCP Registry.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Docker: docker-compose up --build
5. Submit a pull request

Support

For issues related to:

• Twitter API: Check the Twitter API documentation
• MCP Protocol: Check the MCP documentation
• This server: Open an issue in this repository