A comprehensive Model Context Protocol server implementation for X (Twitter) API integration with professional workflow automation, enhanced error handling, and real-time documentation.

• 22 X (Twitter) API Tools - Complete tweet, user, engagement, and list management
• Professional Error Handling - Clear upgrade guidance for API limitations
• 5 Workflow Prompts - Pre-built automation templates
• 6 Dynamic Resources - Real-time API documentation and status
• Full MCP Compliance - Tools, prompts, and resources support

• Node.js 18+
• npm or yarn
• X (Twitter) API credentials (Basic tier minimum - $200/month)

1. Clone and Install

   git clone <repository-url>
   cd twitter-server
   npm install

2. Environment Setup

   cp .env.example .env
   # Edit .env with your X (Twitter) API credentials

3. Build and Run

   npm run build
   npm start

4. Test the Server

   # Test with JSON-RPC calls
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js
   
   # Test specific tool
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

Add these to your .env file:

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

• postTweet - Post new tweets
• getTweetById - Retrieve specific tweets
• replyToTweet - Reply to tweets
• deleteTweet - Delete your tweets

• likeTweet / unlikeTweet - Like/unlike tweets
• retweet / undoRetweet - Retweet/undo retweets
• getRetweets - Get retweet users

• getUserInfo - Get user profiles ✅
• getUserTimeline - Get user tweets ✅
• followUser / unfollowUser - Follow/unfollow users ✅
• getFollowers - Get followers ⚠️ (403 - requires special permissions)
• getFollowing - Get following ⚠️ (403 - requires special permissions)

• createList - Create X (Twitter) lists
• getUserLists - Get user's lists
• addUserToList / removeUserFromList - Manage list members
• getListMembers - Get list members

• searchTweets - Search tweets (requires Pro tier - $5,000/month)
• getHashtagAnalytics - Hashtag analytics (requires Pro tier)
• getLikedTweets - Get liked tweets (API access issue)

Our server includes 5 professional workflow templates:

Interactive guidance for creating engaging tweets with hashtags, mentions, and media.

Comprehensive X (Twitter) analytics workflow for business insights.

Strategic content planning and audience engagement workflows.

Customer service and community engagement best practices.

Industry-specific hashtag research and trend analysis.

Real-time information accessible via MCP:

• API Rate Limits - Live usage monitoring
• Access Level Status - Current tier capabilities
• Tool Status Report - Working vs limited tools
• Quick Start Guide - Getting started documentation
• Workflow Templates - Pre-built automation examples
• User Profile Data - Dynamic user information (live API calls)

# Test working tools
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "postTweet", "arguments": {"text": "Hello from MCP!"}}}' | node dist/index.js

# Test user info
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

# Test limited tools (will show upgrade guidance)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "searchTweets", "arguments": {"query": "MCP"}}}' | node dist/index.js

• 18 Tools Working on Basic tier
• 4 Tools Limited by API tier/permissions
• Professional error messages with upgrade guidance
• All core functionality operational

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/path/to/twitter-server/dist/index.js"],
      "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"
      }
    }
  }
}

# Always source environment first
source .env

# List all tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Call specific tool
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "toolName", "arguments": {"param": "value"}}}' | node dist/index.js

postTweet

{
  "text": "Your tweet content (up to 280 characters)"
}

getTweetById

{
  "tweetId": "1234567890123456789",
  "tweetFields": ["created_at", "public_metrics", "author_id"]
}

replyToTweet

{
  "tweetId": "1234567890123456789", 
  "text": "Your reply content"
}

getUserInfo

{
  "username": "elonmusk",
  "fields": ["description", "public_metrics", "profile_image_url"]
}

followUser

{
  "username": "target_username"
}

likeTweet

{
  "tweetId": "1234567890123456789"
}

retweet

{
  "tweetId": "1234567890123456789"
}

Our enhanced error handling provides:

• Clear API tier explanations for limited tools
• Upgrade pricing information ($5,000/month Pro tier)
• Direct upgrade links to Twitter Developer Portal
• Alternative solution suggestions

Example error response:

{
  "error": "This endpoint requires X (Twitter) API Pro tier access ($5,000/month). Visit https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-leve to upgrade your access level."
}

twitter-server/
├── src/
│   ├── handlers/          # API endpoint handlers
│   ├── prompts.ts        # MCP workflow prompts  
│   ├── resources.ts      # Dynamic MCP resources
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled JavaScript
├── scripts/              # Documentation & PRD
└── package.json

npm run build    # Compile TypeScript
npm start        # Start production server
npm run dev      # Development mode with watch

1. Add handler function in appropriate src/handlers/ file
2. Register tool in src/index.ts
3. Add documentation to this README
4. Test with JSON-RPC calls

1. Follow existing code patterns
2. Add proper error handling with professional messages
3. Test with both working and failing scenarios
4. Update documentation

• searchTweets: Requires Pro tier ($5,000/month)
• getHashtagAnalytics: Requires Pro tier
• getFollowers/getFollowing: Requires special permissions (403 errors)
• getLikedTweets: Parameter validation issues

• Current Setup: Excellent for basic X (Twitter) automation
• For Advanced Analytics: Consider Pro tier upgrade
• For Followers/Following: Request elevated permissions

Error: "fetch is not defined"

# Ensure Node.js 18+ 
node --version

403 Permission Errors

• Check API credentials are correct
• Verify account has required permissions
• Some endpoints need special approval

400 Bad Request Errors

• Review parameter formats
• Check our enhanced error messages for guidance
• Verify API tier supports the endpoint

1. Check error messages - Our enhanced error handling provides clear guidance
2. Review API documentation - X (Twitter) Developer Portal
3. Test with working tools first - Verify basic setup
4. Check environment variables - Ensure all credentials are set

• 22 Total Tools: 18 working, 4 limited
• Professional Error Handling: Clear upgrade guidance
• Full MCP Compliance: Tools, prompts, resources
• Production Ready: Enhanced reliability and UX

Built with ❤️ using the Model Context Protocol