Skip to main content
Glama
enesjakozh
crazyrabbitLTC

Twitter MCP Server

by crazyrabbitLTC
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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

Related MCP server: MCP-Twikit

📋 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

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

How are these scores calculated?

Resources

Tools

View all tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

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