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

• 53 Total Tools - 33 Twitter API + 20 enhanced SocialData.tools research capabilities
• Advanced Analytics - Thread analysis, network mapping, sentiment analysis, viral tracking
• Bypasses API Restrictions - Enhanced research tools work without Pro tier requirements
• Professional Error Handling - Clear upgrade guidance and graceful API key handling
• 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 credentials

   Required Environment Variables:

   # Twitter API credentials (Required)
   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
   
   # SocialData.tools API key (Optional - enables enhanced research tools)
   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   SOCIALDATA_BASE_URL=https://api.socialdata.tools  # Optional, uses default if not set

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)

Note: These tools gracefully handle missing API keys with helpful setup instructions

• advancedTweetSearch - Complex queries with operators, bypasses API tier restrictions
• historicalTweetSearch - Access historical tweets beyond standard API limits
• trendingTopicsSearch - Real-time trend analysis and popular content discovery
• bulkUserProfiles - Multi-user profile analysis in single requests
• userGrowthAnalytics - User growth pattern analysis over time
• userInfluenceMetrics - Engagement scoring and influence calculations

• getFullThread - Reconstruct complete Twitter threads with engagement metrics
• getConversationTree - Map conversation structure including replies and quotes
• getThreadMetrics - Thread performance analysis and engagement distribution

• findMutualConnections - Discover mutual connections via interactions
• analyzeFollowerDemographics - Follower patterns and demographic analysis
• mapInfluenceNetwork - Influence mapping and connection strength analysis

• getHashtagTrends - Hashtag performance tracking over time with trend analysis
• analyzeSentiment - Sentiment analysis with keyword frequency tracking
• trackVirality - Viral spread patterns and engagement velocity analysis

• Various DM and user moderation tools

Get these from Twitter Developer Portal:

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

Enables 20 enhanced research tools that bypass Twitter API limitations:

1. Sign up at SocialData.tools
2. Get your API key from the dashboard
3. Add to .env file:

   SOCIALDATA_API_KEY=your_socialdata_api_key_here

Without SocialData API key: Enhanced research tools will show helpful setup instructions instead of errors.

# Test advanced tweet search (bypasses Twitter API Pro tier requirement)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "AI OR machine learning", "maxResults": 5}}}' | node dist/index.js

# Test sentiment analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "analyzeSentiment", "arguments": {"query": "ChatGPT", "sampleSize": 20}}}' | node dist/index.js

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

# Test thread analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getFullThread", "arguments": {"tweetId": "1234567890123456789"}}}' | node dist/index.js

# These will show helpful setup instructions instead of errors
SOCIALDATA_API_KEY="" echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "test"}}}' | node dist/index.js

1. Start with Twitter API tools for posting, engagement, and basic operations
2. Use SocialData.tools for research, analytics, and advanced insights
3. Combine both for comprehensive Twitter automation and analysis

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

• 53 Total Tools: 33 Twitter API + 20 SocialData.tools enhanced research
• Advanced Analytics: Thread analysis, network mapping, sentiment analysis, viral tracking
• Graceful API Key Handling: Enhanced tools show helpful setup instructions when API key missing
• Bypasses API Restrictions: Research tools work without Twitter Pro tier requirements
• Professional Error Handling: Clear upgrade guidance and user-friendly messages
• Full MCP Compliance: Tools, prompts, resources
• Production Ready: Enhanced reliability, comprehensive analytics, and excellent UX

Built with ❤️ using the Model Context Protocol and SocialData.tools integration