MCP 服务器

MCP Twitter/X Server

Provides integration with Twitter/X, enabling reading posts from users and creating new posts.

README

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

Go to the Twitter Developer Portal
Create a new app or use an existing one
Generate the following credentials:
- API Key
- API Secret
- Access Token
- Access Token Secret
- Bearer Token
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

Clone or download this repository
Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Set up environment variables:
```
cp .env.example .env
```

Option B: Docker Installation

Clone or download this repository
Set up environment variables:
```
cp .env.example .env
```

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

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.