Twitter MCP Server

A powerful Twitter integration for AI agents that leverages the Model Context Protocol (MCP) standard, providing a comprehensive set of Twitter functionality through a clean and consistent interface.

Overview

This server provides access to Twitter's features through MCP tools, allowing seamless integration with AI assistants and other MCP-compatible clients. It's built on top of the agent-twitter-client library and provides robust error handling, rate limiting, and consistent response formatting.

Features

Basic Reading

Get tweets from users with media support
Fetch user profiles with detailed information
Search tweets by hashtags or keywords
Filter search results by latest/top
Rate limiting (max 50 tweets per request)

User Interactions

Like/Unlike tweets
Retweet/Undo retweet
Post tweets with:
- Text content
- Media attachments (images, videos)
- Reply functionality
- Quote tweet capability

Advanced Features

Get user relationships (followers/following)
Fetch trending topics
Access different timeline types:
- Home timeline
- Following timeline
- User timeline
List management (fetch list tweets)

Media & Advanced Interactions

Media handling:
- Image upload (JPEG, PNG, GIF)
- Video upload (MP4)
- Alt text support
Thread creation
Follow/Unfollow users

Tools

Reading Tools

get_tweets - Fetch recent tweets from a user
get_profile - Get a user's profile information
search_tweets - Search for tweets by hashtag or keyword

Interaction Tools

like_tweet - Like or unlike a tweet
retweet - Retweet or undo retweet
post_tweet - Post a new tweet with optional media
create_thread - Create a Twitter thread

Timeline Tools

get_timeline - Get tweets from different timeline types
get_list_tweets - Get tweets from a Twitter list
get_trends - Get current trending topics

User Management Tools

get_user_relationships - Get followers or following list
follow_user - Follow or unfollow a user

Installation

Install dependencies:

npm install

Build the server:

npm run build

Configure environment variables:

# Required: Twitter Account Credentials (for user authentication)
TWITTER_USERNAME=your_username
TWITTER_PASSWORD=your_password
TWITTER_EMAIL=your_email

# Twitter API Authentication (Optional)
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET_KEY=your_api_secret_key
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret

Add the server config to your MCP client:

On MacOS:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "twitter-mcp-server": {
      "command": "/path/to/twitter-mcp-server/build/index.js"
    }
  }
}

Development

For development with auto-rebuild:

npm run watch

Debugging

Since MCP servers communicate over stdio, you can use the MCP Inspector for debugging:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Error Handling

The server implements comprehensive error handling:

Input validation for all parameters
Rate limiting protection
Detailed error messages
Proper error propagation
Logging for debugging

Response Format

All tools return responses in a consistent format:

{
  content: [{
    type: "text",
    text: string // JSON stringified response or error message
  }]
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details