aali-1/twitter-mcp-server

Twitter MCP Server

A Model Context Protocol (MCP) server for Twitter API with posting, searching, and timeline features.

Features

• Post Tweets: Post new tweets with optional reply functionality
• Search Tweets: Search for tweets using query strings
• Get Timelines: Retrieve user timelines
• Rate Limiting: Basic rate limiting for Twitter API calls
• TypeScript: Full TypeScript support with strict type checking
• Testing: Comprehensive test suite with Jest

Prerequisites

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

Installation

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 .env 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

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

MCP Tools

The server provides the following MCP tools:

post_tweet

Post a new tweet with optional reply functionality.

Parameters:

• text (string, required): The text content of the tweet
• reply_to_tweet_id (string, optional): 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): Search query for tweets
• max_results (number, optional): Maximum number of results (default: 10)

Example:

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

get_timeline

Get tweets from a user's timeline.

Parameters:

• username (string, required): Username to get timeline for
• max_results (number, optional): Maximum number of results (default: 10)

Example:

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

get_rate_limit_info

Get current rate limit information.

Parameters: None

Example:

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

Configuration

Environment Variables

Rate Limiting

The server implements basic rate limiting:

• Respects Twitter's API rate limits
• Provides rate limit information via get_rate_limit_info tool
• Graceful error handling for rate limit exceeded scenarios

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

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: Strict type checking
• ESLint: Code linting with TypeScript rules
• Prettier: Code formatting
• Jest: Testing framework

Error Handling

The server includes comprehensive error handling:

• Twitter API errors (rate limits, authentication, etc.)
• Network errors
• Validation errors
• Graceful shutdown handling

Security

• Environment variable validation
• Input validation
• Error handling without information leakage
• Secure credential management

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