Twitter MCP Server

🚀 Twitter MCP Server

A powerful Twitter integration tool designed for AI agents, offering comprehensive Twitter functionality through the Model Context Protocol (MCP) standard with a simple and consistent interface.

🚀 Quick Start

This server provides access to Twitter functionality via MCP tools, enabling 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 a consistent response format.

✨ Features

Basic Reading

• Retrieve user tweets with media support.
• Obtain detailed user profile information.
• Search for tweets by hashtag or keyword.
• Filter search results by latest or popular.
• Rate limit protection (maximum 50 tweets per request).

User Interaction

• Like or unlike tweets.
• Retweet or un-retweet tweets.
• Post tweets with support for:
  • Text content.
  • Media attachments (images, videos).
  • Reply functionality.
  • Quote tweet functionality.

Advanced Features

• Get user relationships (followers/following list).
• Retrieve trending topics.
• Access different timeline types:
  • Active timeline.
  • Following timeline.
  • User timeline.
• List management (get list tweets).

Media and Advanced Interaction

• Media handling:
  • Image upload (JPEG, PNG, GIF).
  • Video upload (MP4).
  • Alt text support.
• Create threads.
• Follow or unfollow users.

🛠️ Tools

Reading Tools

• get_tweets - Retrieve a user's recent tweets.
• get_profile - Get user profile information.
• search_tweets - Search for tweets by hashtag or keyword.

Interaction Tools

• like_tweet - Like or unlike a tweet.
• retweet - Retweet or un-retweet.
• post_tweet - Post a new tweet with attachments.
• create_thread - Create a Twitter thread.

Timeline Tools

• get_timeline - Get tweets from different timeline types.
• get_list_tweets - Get list tweets.
• 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

# Optional: Twitter API authentication
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. Example configuration file:

# Example configuration in .env file
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

💻 Usage Examples

Initialize the server

npm run start

Example commands

# Example of getting tweets
curl -X GET http://localhost:3000/api/tweets

# Example of posting a tweet
curl -X POST http://localhost:3000/api/tweets \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello, Twitter!"}'

🔧 Error Handling

All API requests return a JSON-formatted response:

{
  "success": boolean,
  "error": string|null,
  "result": any
}

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for details.

🤝 Contribution Guidelines

Contributions to this project are welcome via pull requests. Please read the CONTRIBUTING.md file for more information.

Thank you for using the Twitter MCP Server! For assistance, please visit our GitHub page or contact us at support@twittermcp.com.