README - SocialData-MCP-Server by thesethrose

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

Clone or download this repository
Create a virtual environment:

python3 -m venv venv
source venv/bin/activate

Install the required dependencies:

pip install -r requirements.txt

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:

Test the server standalone:

source venv/bin/activate
python server.py

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.

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:

Global webhook (applies to all monitors):

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

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:

Get your API key from your SocialData dashboard
Set it in your MCP client configuration or as an environment variable
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:

Add the tool function with proper type hints
Use the @mcp.tool() decorator
Include comprehensive docstrings
Handle errors appropriately
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