📌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

Clone the repository
Install dependencies: npm install
Copy .env.example to .env and fill in your Twitter API credentials
Build the project: npm run build
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

{
  "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 tweet by ID

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

replyToTweet: Reply to a 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 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

Standardized error responses:

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

Response Format

Successful responses follow this format:

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

Development Commands

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

Status Report of Twitter Tools

Working Tools (✓)

postTweet
Status: Working perfectly
Response: Returns tweet ID
getTweetById
Status: Working perfectly
Response: Returns complete tweet data
likeTweet & unlikeTweet
Status: Working perfectly
Response: Confirmation of action
retweet & undoRetweet
Status: Working perfectly
Response: Confirmation of action
replyToTweet
Status: Working perfectly
Response: Returns reply tweet ID
getUserInfo
Status: Working perfectly
Response: Complete user profile data
followUser & unfollowUser
Status: Working perfectly
Response: Confirmation of action
createList
Status: Working perfectly
Response: Confirmation of list creation
getUserLists
Status: Working perfectly
Response: Returns both owned and member lists

Tools with Issues (⚠️)

getUserTimeline
Status: Error 400
Error: Invalid Request parameters
Fix needed: Parameter validation
searchTweets
Status: Error 400
Error: Invalid Request parameters
Fix needed: Query parameter formatting
getLikedTweets
Status: Error 400
Error: Invalid Request parameters
Fix needed: Parameter validation

Missing Tools (❌)

getHomeTimeline
getFollowers
getFollowing
getHashtagAnalytics

Priority Fixes Needed

Parameter Validation

interface TwitterParamValidator {
  validateTimelineParams(params: any): boolean;
  validateSearchParams(params: any): boolean;
  validateLikedTweetsParams(params: any): boolean;
}

Error Handling

interface TwitterErrorHandler {
  handle400Error(endpoint: string, params: any): void;
  logErrorDetails(error: any): void;
  suggestParameterFixes(params: any): string[];
}

mcp-twitter-server