Skip to main content
Glama
enesjakozh

Twitter MCP Server

by crazyrabbitLTC
npmGitHub
TypeScript
MIT License
6
20
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

ChatGPT Image May 30, 2025, 03_20_40 PM

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

TierCostWorking ToolsLimited Tools
Basic$200/month18/22 toolssearchTweets, getHashtagAnalytics
Pro$5,000/monthAll 22 toolsNone

🛠️ 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 CaseTwitter API ToolSocialData.tools AlternativeAdvantage
Basic SearchsearchTweets ⚠️ (Pro tier $5k/month)advancedTweetSearch ✅Bypasses API restrictions
User AnalysisgetUserInfo ✅userInfluenceMetrics ✅Enhanced analytics
Historical DataLimited by API tierhistoricalTweetSearch ✅Access older tweets
Sentiment AnalysisNot availableanalyzeSentiment ✅Built-in sentiment scoring
Thread AnalysisManual reconstructiongetFullThread ✅Automated thread mapping
Network MappingNot availablemapInfluenceNetwork ✅Connection analysis
Hashtag TrendsgetHashtagAnalytics ⚠️ (Pro tier)getHashtagTrends ✅No tier restrictions
  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

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

Enables interaction with Twitter through a Model Context Protocol, allowing large language models to post tweets, search for tweets, and reply to tweets.

  1. Setup
    1. Environment Variables
      1. Available Tools
        1. Tweet Operations
        2. Search & Analytics
        3. User Operations
        4. Engagement
        5. List Management
      2. Error Handling
        1. Response Format
          1. Development

            Related Resources

            Related MCP Servers

            • Twitter MCP Server

              taazkareem
              -
              security
              F
              license
              -
              quality
              Provides AI agents with comprehensive Twitter functionality through the Model Context Protocol standard, enabling reading tweets, posting content, managing interactions, and accessing timeline data with robust error handling.
              Last updated -
              4
              14
              • Apple

            • MCP-Twikit

              Zo-Valentine
              -
              security
              A
              license
              -
              quality
              A Model Context Protocol server that enables AI to interact with Twitter, allowing functions like searching tweets, comparing sentiments across accounts, and retrieving timeline content.
              Last updated -
              MIT License

            • MCP Twitter

              0xhijo
              -
              security
              A
              license
              -
              quality
              A Model Context Protocol server that enables AI models and applications to interact directly with Twitter/X, providing capabilities to create posts, reply to tweets, retrieve user data, and manage account actions.
              Last updated -
              1
              9
              MIT License

            • Agent Twitter Client MCP

              ryanmac
              -
              security
              A
              license
              -
              quality
              A Model Context Protocol server that enables AI agents to interact with Twitter without direct API access, supporting tweet operations, user interactions, and Grok AI integration.
              Last updated -
              10
              16
              MIT License
              • Apple

            View all related MCP servers

            Appeared in Searches

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/crazyrabbitLTC/mcp-twitter-server'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server