X (Twitter) MCP Server

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

🚀 Features

• 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

📋 Quick Start

Prerequisites

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

Local Installation

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
   

🔑 X (Twitter) API Setup

Required Credentials

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

API Access Levels

| Tier | Cost | Working Tools | Limited Tools | |------|------|---------------|---------------| | Basic | $200/month | 18/22 tools | searchTweets, getHashtagAnalytics | | Pro | $5,000/month | All 22 tools | None |

🛠️ Available Tools (53 Total)

🐦 Twitter API Tools (33 tools)

✅ Tweet Operations (All Working)

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

✅ Engagement (All Working)

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

✅ User Management (Most Working)

• 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)

✅ List Management (All Working)

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

⚠️ Search & Analytics (Limited)

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

🔍 SocialData.tools Enhanced Research (20 tools)

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

🔎 Advanced Search (6 tools)

• 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

🧵 Thread & Conversation Analysis (3 tools)

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

🌐 Network Analysis (3 tools)

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

📈 Advanced Analytics (3 tools)

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

📱 Direct Messages & Moderation (5 tools)

• Various DM and user moderation tools

🔑 API Keys Setup

Twitter API (Required)

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

SocialData.tools API (Optional)

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.

🧪 Testing SocialData.tools Integration

Test Enhanced Research Tools

# 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

Test Without API Key

# 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

🆚 When to Use Which Tools

Twitter API vs SocialData.tools Comparison

| Use Case | Twitter API Tool | SocialData.tools Alternative | Advantage | |----------|------------------|-------------------------------|-----------| | Basic Search | searchTweets ⚠️ (Pro tier $5k/month) | advancedTweetSearch ✅ | Bypasses API restrictions | | User Analysis | getUserInfo ✅ | userInfluenceMetrics ✅ | Enhanced analytics | | Historical Data | Limited by API tier | historicalTweetSearch ✅ | Access older tweets | | Sentiment Analysis | Not available | analyzeSentiment ✅ | Built-in sentiment scoring | | Thread Analysis | Manual reconstruction | getFullThread ✅ | Automated thread mapping | | Network Mapping | Not available | mapInfluenceNetwork ✅ | Connection analysis | | Hashtag Trends | getHashtagAnalytics ⚠️ (Pro tier) | getHashtagTrends ✅ | No tier restrictions |

Recommended Workflow

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

🎯 MCP Workflow Prompts

Our server includes 5 professional workflow templates:

1. Tweet Composition (compose-tweet)

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

2. Analytics Reporting (analytics-report)

Comprehensive X (Twitter) analytics workflow for business insights.

3. Content Strategy (content-strategy)

Strategic content planning and audience engagement workflows.

4. Community Management (community-management)

Customer service and community engagement best practices.

5. Hashtag Research (hashtag-research)

Industry-specific hashtag research and trend analysis.

📊 Dynamic Resources

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)

🧪 Testing

Manual Testing

# 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

Test Results Summary

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

🔧 Integration Examples

MCP Client (Cursor/Claude)

{
  "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"
      }
    }
  }
}

Direct JSON-RPC

# 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

📝 API Documentation

Tweet Operations

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"
}

User Operations

getUserInfo

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

followUser

{
  "username": "target_username"
}

Engagement

likeTweet

{
  "tweetId": "1234567890123456789"
}

retweet

{
  "tweetId": "1234567890123456789"
}

🚨 Error Handling

Professional Error Messages

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."
}

📁 Project Structure

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

🔄 Development

Build & Run

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

Adding New Tools

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

Contributing

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

📋 Known Limitations

API Tier Restrictions

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

Recommendations

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

🆘 Troubleshooting

Common Issues

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

Getting Help

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

---

📊 Current Status

• 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