Twitter MCP Server

🚀 Twitter MCP Server

A Model Context Protocol (MCP) server for the Twitter API, offering features such as posting tweets, searching for tweets, and retrieving timelines.

✨ Features

• Post Tweets: Publish new tweets with an optional reply feature.
• Search Tweets: Look for tweets using query strings.
• Get Timelines: Fetch user timelines.
• Rate Limiting: Implement basic rate limiting for Twitter API calls.
• TypeScript: Enjoy full TypeScript support with strict type checking.
• Testing: Benefit from a comprehensive test suite powered by Jest.

📦 Installation

Prerequisites

• Node.js 18+
• Twitter API credentials (API Key, API Secret, Access Token, Access Token Secret, Bearer Token)

Steps

1. Clone the repository:

git clone https://github.com/aali-1/twitter-mcp-server.git
cd twitter-mcp-server

2. Install dependencies:

npm install

3. Set up environment variables:

cp env.example .env

Edit the .env file with your Twitter API credentials:

TWITTER_API_KEY=your_twitter_api_key
TWITTER_API_SECRET=your_twitter_api_secret
TWITTER_ACCESS_TOKEN=your_twitter_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_twitter_access_token_secret
TWITTER_BEARER_TOKEN=your_twitter_bearer_token

💻 Usage Examples

Build and Run

# Build the project
npm run build

# Run the MCP server
npm start

Development

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

📚 Documentation

MCP Tools

The server offers the following MCP tools:

Basic Usage

post_tweet

Post a new tweet with an optional reply feature. Parameters:

• text (string, required): The text content of the tweet.
• reply_to_tweet_id (string, optional): The Tweet ID to reply to. Example:

{
  "name": "post_tweet",
  "arguments": {
    "text": "Hello, world!",
    "reply_to_tweet_id": "1234567890123456789"
  }
}

search_tweets (Requires Basic/Pro plan)

Search for tweets using a query string. Parameters:

• query (string, required): The search query for tweets.
• max_results (number, optional): The maximum number of results (default: 10). Example:

{
  "name": "search_tweets",
  "arguments": {
    "query": "AI",
    "max_results": 5
  }
}

get_timeline

Retrieve tweets from a user's timeline. Parameters:

• username (string, required): The username to get the timeline for.
• max_results (number, optional): The maximum number of results (default: 10). Example:

{
  "name": "get_timeline",
  "arguments": {
    "username": "elonmusk",
    "max_results": 5
  }
}

get_rate_limit_info

Get the current rate limit information. Parameters: None Example:

{
  "name": "get_rate_limit_info",
  "arguments": {}
}

Configuration

Environment Variables

Rate Limiting

The server implements basic rate limiting:

• It adheres to Twitter's API rate limits.
• It provides rate limit information via the get_rate_limit_info tool.
• It handles rate limit exceeded scenarios gracefully.

Project Structure

src/
├── config.ts          # Configuration management
├── logger.ts          # Logging utilities
├── server.ts          # MCP server implementation
├── twitter.ts         # Twitter API service
├── types.ts           # TypeScript type definitions
├── index.ts           # Main entry point
└── test/              # Test files
    ├── basic.test.ts
    └── twitter.test.ts

Testing

The project includes comprehensive tests:

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

The tests cover:

• Twitter service functionality
• Rate limiting
• Error handling
• Tool parameter validation

Development

Available Scripts

npm run dev          # Start in development mode
npm run build        # Build TypeScript
npm run start        # Start production server
npm run test         # Run tests
npm run lint         # Run ESLint
npm run format       # Format code with Prettier

Code Quality

• TypeScript: Enables strict type checking.
• ESLint: Performs code linting with TypeScript rules.
• Prettier: Handles code formatting.
• Jest: Serves as the testing framework.

Error Handling

The server features comprehensive error handling:

• It deals with Twitter API errors (rate limits, authentication, etc.).
• It manages network errors.
• It handles validation errors.
• It ensures graceful shutdown handling.

Security

• It validates environment variables.
• It validates input.
• It handles errors without leaking information.
• It manages credentials securely.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests.
5. Submit a pull request.

📄 License

MIT License