X (Twitter) MCP server

This MCP server provides a comprehensive integration with X (Twitter) API, offering 53 tools for social media automation, analytics, and research. It combines standard Twitter API capabilities with enhanced research tools from SocialData.tools to bypass typical API restrictions.

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• X (Twitter) API credentials (Basic tier minimum - $200/month)

Setup Steps

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
   

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
   

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.

Available Tools

Twitter API Tools (33 tools)

Tweet Operations

• postTweet - Post new tweets
• getTweetById - Retrieve specific tweets
• replyToTweet - Reply to tweets
• deleteTweet - Delete your tweets

Engagement

• likeTweet / unlikeTweet - Like/unlike tweets
• retweet / undoRetweet - Retweet/undo retweets
• getRetweets - Get retweet users

User Management

• getUserInfo - Get user profiles
• getUserTimeline - Get user tweets
• followUser / unfollowUser - Follow/unfollow users
• getFollowers - Get followers (requires special permissions)
• getFollowing - Get following (requires special permissions)

List Management

• createList - Create X (Twitter) lists
• getUserLists - Get user's lists
• addUserToList / removeUserFromList - Manage list members
• getListMembers - Get list members

Search & Analytics

• 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)

Advanced Search

• advancedTweetSearch - Complex queries with operators
• historicalTweetSearch - Access historical tweets
• trendingTopicsSearch - Real-time trend analysis
• bulkUserProfiles - Multi-user profile analysis
• userGrowthAnalytics - User growth pattern analysis
• userInfluenceMetrics - Engagement scoring and influence calculations

Thread & Conversation Analysis

• getFullThread - Reconstruct complete Twitter threads
• getConversationTree - Map conversation structure
• getThreadMetrics - Thread performance analysis

Network Analysis

• findMutualConnections - Discover mutual connections
• analyzeFollowerDemographics - Follower patterns analysis
• mapInfluenceNetwork - Influence mapping

Advanced Analytics

• getHashtagTrends - Hashtag performance tracking
• analyzeSentiment - Sentiment analysis
• trackVirality - Viral spread patterns analysis

Testing Examples

Basic Twitter API Testing

# Test user info
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

# Post a tweet
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "postTweet", "arguments": {"text": "Hello from MCP!"}}}' | node dist/index.js

SocialData.tools Testing

# Test advanced tweet search
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

Integration with MCP Clients

MCP Client Configuration

{
  "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"
      }
    }
  }
}

Troubleshooting

Common Issues

Error: "fetch is not defined"

• Ensure Node.js 18+ is installed: 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 error messages for guidance
• Verify API tier supports the endpoint

API Tier Considerations

Tier	Cost	Working Tools	Limited Tools
Basic	$200/month	18/22 tools	searchTweets, getHashtagAnalytics
Pro	$5,000/month	All 22 tools	None

The SocialData.tools integration provides alternatives to many restricted features without requiring the Pro tier.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "x-twitter" '{"command":"node","args":["dist/index.js"],"env":{"X_API_KEY":"${X_API_KEY}","X_API_SECRET":"${X_API_SECRET}","X_ACCESS_TOKEN":"${X_ACCESS_TOKEN}","X_ACCESS_TOKEN_SECRET":"${X_ACCESS_TOKEN_SECRET}","SOCIALDATA_API_KEY":"${SOCIALDATA_API_KEY}"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "x-twitter": {
            "command": "node",
            "args": [
                "dist/index.js"
            ],
            "env": {
                "X_API_KEY": "${X_API_KEY}",
                "X_API_SECRET": "${X_API_SECRET}",
                "X_ACCESS_TOKEN": "${X_ACCESS_TOKEN}",
                "X_ACCESS_TOKEN_SECRET": "${X_ACCESS_TOKEN_SECRET}",
                "SOCIALDATA_API_KEY": "${SOCIALDATA_API_KEY}"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "x-twitter": {
            "command": "node",
            "args": [
                "dist/index.js"
            ],
            "env": {
                "X_API_KEY": "${X_API_KEY}",
                "X_API_SECRET": "${X_API_SECRET}",
                "X_ACCESS_TOKEN": "${X_ACCESS_TOKEN}",
                "X_ACCESS_TOKEN_SECRET": "${X_ACCESS_TOKEN_SECRET}",
                "SOCIALDATA_API_KEY": "${SOCIALDATA_API_KEY}"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect