📌Overview

Purpose: The Twitter MCP Server serves as a Model Context Protocol server implementation for seamless integration with the Twitter API.

Overview: This server allows developers to interact with Twitter by providing tools for tweet management, user operations, engagement activities, search, and analytics, leveraging the Twitter API. It simplifies complex API interactions into easy-to-use endpoints.

Key Features:

• Tweet Operations: Includes functionalities to post, reply, delete tweets, and manage media attachments, enabling comprehensive tweet management.

• Search & Analytics: Provides tools for searching tweets and retrieving analytics on hashtags, facilitating data-driven insights and engagements.

• User Operations: Allows retrieval of user information and timelines, enhancing user interaction and engagement metrics analysis.

• Engagement: Features for liking, unliking, retweeting, and managing retweets to enable effective engagement with content.

• List Management: Supports creating and managing lists to organize users effectively, enhancing social media strategy execution.

---

Twitter MCP Server

A Model Context Protocol server implementation for Twitter API integration.

Setup

1. Clone the repository
2. Install dependencies: npm install
3. Copy .env.example to .env and fill in your Twitter API credentials
4. Build the project: npm run build
5. Start the server: npm start

Environment Variables

Required Twitter API credentials in .env:

X_API_KEY=your_api_key
X_API_SECRET=your_api_secret
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret

Available Tools

Tweet Operations

• postTweet: Post a new tweet

  {
    "text": "Your tweet text here"
  }
  

• postTweetWithMedia: Post a tweet with media attachment

  {
    "text": "Your tweet text",
    "mediaPath": "path/to/media/file",
    "mediaType": "image/jpeg|image/png|image/gif|video/mp4",
    "altText": "Optional alt text for accessibility"
  }
  

• getTweetById: Get a specific tweet by ID

  {
    "tweetId": "tweet_id",
    "tweetFields": ["created_at", "public_metrics"]
  }
  

• replyToTweet: Reply to an existing tweet

  {
    "tweetId": "tweet_id",
    "text": "Your reply text"
  }
  

• deleteTweet: Delete a tweet

  {
    "tweetId": "tweet_id"
  }
  

Search & Analytics

• searchTweets: Search for tweets

  {
    "query": "search query",
    "maxResults": 10,
    "tweetFields": ["created_at", "public_metrics"]
  }
  

• getHashtagAnalytics: Get analytics for a hashtag

  {
    "hashtag": "hashtag",
    "startTime": "ISO-8601 date",
    "endTime": "ISO-8601 date"
  }
  

User Operations

• getUserInfo: Get user information

  {
    "username": "twitter_username",
    "fields": ["description", "public_metrics"]
  }
  

• getUserTimeline: Get user's tweets

  {
    "username": "twitter_username",
    "maxResults": 10,
    "tweetFields": ["created_at", "public_metrics"]
  }
  

• getFollowers: Get user's followers

  {
    "username": "twitter_username",
    "maxResults": 100,
    "userFields": ["description", "public_metrics"]
  }
  

• getFollowing: Get accounts a user follows

  {
    "username": "twitter_username",
    "maxResults": 100,
    "userFields": ["description", "public_metrics"]
  }
  

Engagement

• likeTweet: Like a tweet

  {
    "tweetId": "tweet_id"
  }
  

• unlikeTweet: Unlike a tweet

  {
    "tweetId": "tweet_id"
  }
  

• retweet: Retweet a tweet

  {
    "tweetId": "tweet_id"
  }
  

• undoRetweet: Undo a retweet

  {
    "tweetId": "tweet_id"
  }
  

• getRetweets: Get users who retweeted a tweet

  {
    "tweetId": "tweet_id",
    "maxResults": 100,
    "userFields": ["description", "public_metrics"]
  }
  

• getLikedTweets: Get tweets liked by a user

  {
    "userId": "user_id",
    "maxResults": 100,
    "tweetFields": ["created_at", "public_metrics"]
  }
  

List Management

• createList: Create a new list

  {
    "name": "List name",
    "description": "List description",
    "isPrivate": false
  }
  

• addUserToList: Add a user to a list

  {
    "listId": "list_id",
    "username": "twitter_username"
  }
  

• removeUserFromList: Remove a user from a list

  {
    "listId": "list_id",
    "username": "twitter_username"
  }
  

• getListMembers: Get members of a list

  {
    "listId": "list_id",
    "maxResults": 100,
    "userFields": ["description", "public_metrics"]
  }
  

Error Handling

All tools return standardized error responses:

• Missing parameters: Missing required parameter: parameter_name
• API errors: Error message from Twitter API
• Not found errors: Appropriate "not found" message for the resource

Response Format

All successful responses follow this format:

{
  "content": [
    {
      "type": "text",
      "text": "Operation result message"
    }
  ]
}

Development

• Build: npm run build
• Start: npm start
• Watch mode: npm run dev

Status Report

Working Tools (✓)

1. postTweet: Working perfectly
2. getTweetById: Working perfectly
3. likeTweet & unlikeTweet: Working perfectly
4. retweet & undoRetweet: Working perfectly
5. replyToTweet: Working perfectly
6. getUserInfo: Working perfectly
7. createList: Working perfectly
8. getUserLists: Working perfectly

Tools with Issues (⚠️)

1. getUserTimeline: Error 400
2. searchTweets: Error 400
3. getLikedTweets: Error 400

Missing Tools (❌)

• getHomeTimeline
• getFollowers
• getFollowing
• getHashtagAnalytics

Priority Fixes Needed

1. Parameter Validation
2. Error Handling