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

Related MCP server: MCP-Twikit

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