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
-
Clone and Install
git clone <repository-url> cd twitter-server npm install -
Environment Setup
cp .env.example .env # Edit .env with your credentialsRequired 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 -
Build and Run
npm run build npm start -
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 tweetsgetTweetById- Retrieve specific tweetsreplyToTweet- Reply to tweetsdeleteTweet- Delete your tweets
✅ Engagement (All Working)
likeTweet/unlikeTweet- Like/unlike tweetsretweet/undoRetweet- Retweet/undo retweetsgetRetweets- 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) listsgetUserLists- Get user's listsaddUserToList/removeUserFromList- Manage list membersgetListMembers- 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 restrictionshistoricalTweetSearch- Access historical tweets beyond standard API limitstrendingTopicsSearch- Real-time trend analysis and popular content discoverybulkUserProfiles- Multi-user profile analysis in single requestsuserGrowthAnalytics- User growth pattern analysis over timeuserInfluenceMetrics- Engagement scoring and influence calculations
🧵 Thread & Conversation Analysis (3 tools)
getFullThread- Reconstruct complete Twitter threads with engagement metricsgetConversationTree- Map conversation structure including replies and quotesgetThreadMetrics- Thread performance analysis and engagement distribution
🌐 Network Analysis (3 tools)
findMutualConnections- Discover mutual connections via interactionsanalyzeFollowerDemographics- Follower patterns and demographic analysismapInfluenceNetwork- Influence mapping and connection strength analysis
📈 Advanced Analytics (3 tools)
getHashtagTrends- Hashtag performance tracking over time with trend analysisanalyzeSentiment- Sentiment analysis with keyword frequency trackingtrackVirality- 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:
- Sign up at SocialData.tools
- Get your API key from the dashboard
- 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
- Start with Twitter API tools for posting, engagement, and basic operations
- Use SocialData.tools for research, analytics, and advanced insights
- 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
- Add handler function in appropriate
src/handlers/file - Register tool in
src/index.ts - Add documentation to this README
- Test with JSON-RPC calls
Contributing
- Follow existing code patterns
- Add proper error handling with professional messages
- Test with both working and failing scenarios
- 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
- Check error messages - Our enhanced error handling provides clear guidance
- Review API documentation - X (Twitter) Developer Portal
- Test with working tools first - Verify basic setup
- 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