Twitter MCP Server

🚀 Twitter MCP Server

A powerful Twitter integration for AI agents that uses the Model Context Protocol (MCP) standard. It offers a wide range of Twitter features through a clean and consistent interface.

🚀 Quick Start

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

✨ Features

Basic Reading

• Retrieve tweets from users with media support.
• Fetch user profiles with detailed information.
• Search for tweets by hashtags or keywords.
• Filter search results by latest or top.
• Rate limiting (maximum of 50 tweets per request).

User Interactions

• Like or unlike tweets.
• Retweet or 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 or 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

1. Install dependencies:

npm install

2. Build the server:

npm run build

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

4. 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"
    }
  }
}

💻 Usage Examples

Basic Usage

# Install dependencies
npm install

# Build the server
npm run build

Advanced Usage

# For development with auto - rebuild
npm run watch

# Debugging with MCP Inspector
npm run inspector

🔧 Technical Details

Error Handling

The server implements comprehensive error handling, including input validation for all parameters, rate limiting protection, detailed error messages, proper error propagation, and 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

This project is under the MIT License. See the LICENSE file for details.