Twitter MCP Server

 # 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** ```bash git clone <repository-url> cd twitter-server npm install ``` 2. **Environment Setup** ```bash cp .env.example .env # Edit .env with your credentials ``` **Required Environment Variables:** ```env # 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** ```bash npm run build npm start ``` 4. **Test the Server** ```bash # 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: ```env 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](https://developer.twitter.com/): ```env 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](https://socialdata.tools) 2. **Get your API key** from the dashboard 3. **Add to .env file:** ```env 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 ```bash # 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 ```bash # 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 ```bash # 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) ```json { "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 ```bash # 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** ```json { "text": "Your tweet content (up to 280 characters)" } ``` **getTweetById** ```json { "tweetId": "1234567890123456789", "tweetFields": ["created_at", "public_metrics", "author_id"] } ``` **replyToTweet** ```json { "tweetId": "1234567890123456789", "text": "Your reply content" } ``` ### User Operations **getUserInfo** ```json { "username": "elonmusk", "fields": ["description", "public_metrics", "profile_image_url"] } ``` **followUser** ```json { "username": "target_username" } ``` ### Engagement **likeTweet** ```json { "tweetId": "1234567890123456789" } ``` **retweet** ```json { "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: ```json { "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 ```bash 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"** ```bash # 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