Mcp Twitter 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

Clone and Install

git clone <repository-url>
cd twitter-server
npm install

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

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 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:

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

X (Twitter) MCP Server

🚀 Features

📋 Quick Start

Prerequisites

Local Installation

🔑 X (Twitter) API Setup

Required Credentials

API Access Levels

🛠️ Available Tools (53 Total)

🐦 Twitter API Tools (33 tools)

✅ Tweet Operations (All Working)

✅ Engagement (All Working)

✅ User Management (Most Working)

✅ List Management (All Working)

⚠️ Search & Analytics (Limited)

🔍 SocialData.tools Enhanced Research (20 tools)

🔎 Advanced Search (6 tools)

🧵 Thread & Conversation Analysis (3 tools)

🌐 Network Analysis (3 tools)

📈 Advanced Analytics (3 tools)

📱 Direct Messages & Moderation (5 tools)

🔑 API Keys Setup

Twitter API (Required)

SocialData.tools API (Optional)

🧪 Testing SocialData.tools Integration

Test Enhanced Research Tools

Test Without API Key

🆚 When to Use Which Tools

Twitter API vs SocialData.tools Comparison

Recommended Workflow

🎯 MCP Workflow Prompts

1. Tweet Composition (compose-tweet)

2. Analytics Reporting (analytics-report)

3. Content Strategy (content-strategy)

4. Community Management (community-management)

5. Hashtag Research (hashtag-research)

📊 Dynamic Resources

🧪 Testing

Manual Testing

Test Results Summary

🔧 Integration Examples

MCP Client (Cursor/Claude)

Direct JSON-RPC

📝 API Documentation

Tweet Operations

User Operations

Engagement

🚨 Error Handling

Professional Error Messages

📁 Project Structure

🔄 Development

Build & Run

Adding New Tools

Contributing

📋 Known Limitations

API Tier Restrictions

Recommendations

🆘 Troubleshooting

Common Issues

Getting Help

📊 Current Status

Prerequisites

Recommended Server

Details

Share

More Server

Nmap Mcp Server

Logseq Mcp

Mcp Llms Txt Explorer

Twitch Mcp Server

1. Tweet Composition (`compose-tweet`)

2. Analytics Reporting (`analytics-report`)

3. Content Strategy (`content-strategy`)

4. Community Management (`community-management`)

5. Hashtag Research (`hashtag-research`)