SocialData MCP Server

A comprehensive Model Context Protocol (MCP) server that provides tools for interacting with the SocialData API. This server allows you to fetch Twitter/X data, monitor user activity, and analyze social media engagement programmatically.

Features

Data Retrieval

• Search: Advanced Twitter search with operators
• User Profiles: Get detailed user information by username or ID
• Followers/Following: Retrieve follower and following lists
• Tweets: Get user tweets, mentions, highlights, and threads
• Lists & Communities: Access Twitter Lists and Community data
• Spaces: Get Twitter Space details

Social Actions Verification

• Following Verification: Check if one user follows another
• Retweet Verification: Verify if a user retweeted a tweet
• Comment Verification: Check if a user commented on a tweet

Monitoring & Alerts

• User Tweet Monitors: Get alerts for new tweets
• Following Monitors: Monitor when users follow new accounts
• Profile Monitors: Track profile changes
• Pump.fun Monitors: Monitor cryptocurrency mentions

Account Management

• Balance Tracking: Check remaining API credits
• Webhook Management: Set up notification endpoints

Installation

Option 1: Automated Setup (Recommended)

Run the setup script which will create a virtual environment and install dependencies:

chmod +x setup.sh
./setup.sh

Then activate the virtual environment:

source venv/bin/activate

Option 2: Manual Setup

1. Clone or download this repository
2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate

3. Install the required dependencies:

pip install -r requirements.txt

4. Set up your SocialData API key as an environment variable:

export SOCIALDATA_API_KEY="your_api_key_here"

You can get an API key from your SocialData dashboard.

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop, Continue, or other MCP-compatible tools), add the following configuration:

For MCP Clients

Add this to your MCP client configuration file (usually config.json or similar):

{
    "mcpServers": {
        "socialdata": {
            "type": "stdio",
            "command": "/path/to/your/socialdata/venv/bin/python",
            "args": ["/path/to/your/socialdata/server.py"],
            "env": {
                "SOCIALDATA_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Configuration Options

Replace the paths and API key with your actual values:

• /path/to/your/socialdata/ - Replace with the full path to where you installed this server
• your_actual_api_key_here - Replace with your SocialData API key from your dashboard

Example Configurations

Option 1: Using Virtual Environment Python (Recommended)

{
    "mcpServers": {
        "socialdata": {
            "type": "stdio",
            "command": "/Users/yourname/path/to/socialdata/venv/bin/python",
            "args": ["/Users/yourname/path/to/socialdata/server.py"],
            "env": {
                "SOCIALDATA_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Option 2: Using System Python

{
    "mcpServers": {
        "socialdata": {
            "type": "stdio",
            "command": "python3",
            "args": ["/Users/yourname/path/to/socialdata/server.py"],
            "env": {
                "SOCIALDATA_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Option 3: Using a Wrapper Script

Create a run script:

#!/bin/bash
cd /path/to/your/socialdata
source venv/bin/activate
python3 server.py

Then configure:

{
    "mcpServers": {
        "socialdata": {
            "type": "stdio",
            "command": "/path/to/your/socialdata/run.sh",
            "args": [],
            "env": {
                "SOCIALDATA_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Finding Your Installation Path

To find the correct path for your installation:

# Navigate to your socialdata directory
cd /path/to/your/socialdata

# Get the full path
pwd

# This will show something like:
# /Users/yourname/Agents/MCP/socialdata

Use this full path in your MCP client configuration.

Usage

Running the Server Standalone

Make sure your virtual environment is activated first:

source venv/bin/activate
python server.py

When you're done, you can deactivate the virtual environment:

deactivate

Available Tools

Search & Discovery

search_twitter

Search Twitter with advanced operators.

Parameters:

• query (required): Search query with Twitter operators
• cursor (optional): Pagination cursor
• search_type (optional): "Top" or "Latest"

Example:

# Search for tweets from Elon Musk about Dogecoin, excluding replies
search_twitter("from:elonmusk doge -filter:replies")

# Search for latest tweets about AI
search_twitter("AI", search_type="Latest")

User Information

get_user_by_username

Get user profile by Twitter username.

get_user_by_id

Get user profile by Twitter user ID.

get_multiple_users_by_usernames

Get up to 100 user profiles by usernames.

get_user_complete_profile

Get comprehensive user data including bio, recent tweets, and extended information.

Example:

# Get basic user info
user = get_user_by_username("elonmusk")

# Get complete profile with recent tweets
complete_profile = get_user_complete_profile("elonmusk")

User Connections

get_user_followers

Get followers of a user.

get_user_verified_followers

Get only verified followers.

get_user_following

Get users that someone is following.

Example:

# Get Elon Musk's followers
followers = get_user_followers("44196397")  # Elon's user ID

# Get verified followers only
verified = get_user_verified_followers("44196397")

Tweet Operations

get_tweet

Get complete tweet details.

get_tweet_comments

Get comments/replies to a tweet.

get_tweet_retweeters

Get users who retweeted a tweet.

get_tweet_quotes

Get quote tweets.

get_twitter_thread

Get all tweets in a thread.

analyze_tweet_engagement

Get comprehensive engagement data (comments, retweets, quotes).

Example:

# Get tweet details
tweet = get_tweet("1234567890")

# Analyze full engagement
engagement = analyze_tweet_engagement("1234567890")

Social Verification

verify_user_following

Check if one user follows another.

verify_user_retweeted

Verify if a user retweeted a specific tweet.

verify_user_commented

Check if a user commented on a tweet.

Example:

# Check if user A follows user B
following = verify_user_following(
    source_user_id="123456",
    target_user_id="789012"
)

# Verify retweet
retweeted = verify_user_retweeted(
    tweet_id="1234567890",
    user_id="123456"
)

Monitoring

create_user_tweets_monitor

Monitor new tweets from a user.

create_user_following_monitor

Monitor when a user follows new accounts.

create_user_profile_monitor

Monitor profile changes.

list_monitors

List all active monitors.

delete_monitor

Remove a monitor.

Example:

# Monitor Elon Musk's tweets
monitor = create_user_tweets_monitor(
    user_id="44196397",
    webhook_url="https://your-webhook.com/notify"
)

# List all monitors
monitors = list_monitors()

# Delete a monitor
delete_monitor("monitor_123")

Account Management

get_account_balance

Check remaining API credits.

set_global_webhook

Set default webhook URL for all monitors.

Advanced Usage Examples

1. Comprehensive User Analysis

# Get complete user profile
profile = get_user_complete_profile("username")

# Get their followers and following
followers = get_user_followers(profile["id_str"])
following = get_user_following(profile["id_str"])

# Get their recent tweets with engagement
tweets = get_user_tweets(profile["id_str"])
for tweet in tweets["tweets"][:5]:  # Analyze top 5 tweets
    engagement = analyze_tweet_engagement(tweet["id_str"])

2. Monitor Competitor Activity

# Set up monitoring for competitor accounts
competitors = ["competitor1_id", "competitor2_id", "competitor3_id"]

for user_id in competitors:
    # Monitor their tweets
    create_user_tweets_monitor(user_id, webhook_url="https://your-app.com/competitor-tweets")
    
    # Monitor profile changes
    create_user_profile_monitor(user_id, webhook_url="https://your-app.com/profile-changes")

3. Engagement Campaign Verification

# Verify campaign participants
campaign_tweet_id = "1234567890"
participant_ids = ["user1", "user2", "user3"]

results = {}
for user_id in participant_ids:
    results[user_id] = {
        "retweeted": verify_user_retweeted(campaign_tweet_id, user_id),
        "commented": verify_user_commented(campaign_tweet_id, user_id),
        "following": verify_user_following(user_id, "your_brand_id")
    }

4. Trending Topic Analysis

# Search for trending topic
search_results = search_twitter("#AI OR #MachineLearning", search_type="Latest")

# Analyze engagement for top tweets
for tweet in search_results["tweets"][:10]:
    engagement = analyze_tweet_engagement(tweet["id_str"])
    print(f"Tweet: {tweet['text'][:100]}...")
    print(f"Engagement: {len(engagement['comments'])} comments, "
          f"{len(engagement['retweeters'])} retweets")

Testing Your Setup

To verify your server is working correctly:

1. Test the server standalone:

   source venv/bin/activate
   python server.py
   

2. Test with your MCP client: Once configured, try using one of the available tools like get_account_balance to verify the connection and API key.

3. Check API balance:

   balance = get_account_balance()
   print(f"Remaining balance: ${balance['balance_usd']}")
   

Error Handling

The server includes comprehensive error handling for:

• Invalid API keys
• Rate limiting
• Network errors
• Invalid parameters
• Missing data

All errors are returned as descriptive exception messages.

API Costs

SocialData API charges based on usage. Check your balance regularly:

balance = get_account_balance()
print(f"Remaining balance: ${balance['balance']}")

Rate Limits

SocialData handles rate limiting automatically. The API is designed to be reliable and scalable without requiring proxy management.

Webhook Configuration

For monitoring features, you can set up webhooks to receive real-time notifications:

1. Global webhook (applies to all monitors):

   set_global_webhook("https://your-app.com/webhook")
   

2. Monitor-specific webhooks (overrides global):

   create_user_tweets_monitor(
       user_id="123456",
       webhook_url="https://your-app.com/specific-webhook"
   )
   

API Key Management

The server looks for the API key in the SOCIALDATA_API_KEY environment variable. Make sure to:

1. Get your API key from your SocialData dashboard
2. Set it in your MCP client configuration or as an environment variable
3. Keep your API key secure and never commit it to version control

Development

Project Structure

socialdata/
├── server.py          # Main MCP server implementation
├── config.json        # MCP server configuration
├── requirements.txt   # Python dependencies
├── setup.sh          # Automated setup script
├── .env.example       # Environment variable template
├── .gitignore         # Git ignore rules
├── openapi.yml        # API specification reference
└── README.md          # This file

Adding New Features

The server is built using FastMCP and follows the SocialData API specification. To add new endpoints:

1. Add the tool function with proper type hints
2. Use the @mcp.tool() decorator
3. Include comprehensive docstrings
4. Handle errors appropriately
5. Update the config.json with the new tool

Support

If you find this project helpful, consider:

• ⭐ Starring this repository
• Supporting my work on GitHub Sponsors
• 🌐 Visiting my website at SethRose.dev

Compliance

When using this server:

• Respect Twitter's Terms of Service
• Follow data privacy regulations
• Use monitoring responsibly
• Don't exceed reasonable request rates
• Comply with user privacy expectations

License

This project is open source and available under the MIT License.

---

Created by Seth Rose | GitHub