README.md•13.3 kB
# 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.
[](https://github.com/sponsors/TheSethRose)
[](https://sethrose.dev)
## 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:
```bash
chmod +x setup.sh
./setup.sh
```
Then activate the virtual environment:
```bash
source venv/bin/activate
```
### Option 2: Manual Setup
1. Clone or download this repository
2. Create a virtual environment:
```bash
python3 -m venv venv
source venv/bin/activate
```
3. Install the required dependencies:
```bash
pip install -r requirements.txt
```
4. Set up your SocialData API key as an environment variable:
```bash
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):
```json
{
"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)
```json
{
"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
```json
{
"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:
```bash
#!/bin/bash
cd /path/to/your/socialdata
source venv/bin/activate
python3 server.py
```
Then configure:
```json
{
"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:
```bash
# 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:
```bash
source venv/bin/activate
python server.py
```
When you're done, you can deactivate the virtual environment:
```bash
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:**
```python
# 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:**
```python
# 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:**
```python
# 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:**
```python
# 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:**
```python
# 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:**
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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**:
```bash
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**:
```python
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:
```python
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):
```python
set_global_webhook("https://your-app.com/webhook")
```
2. **Monitor-specific webhooks** (overrides global):
```python
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
- [](https://github.com/sponsors/TheSethRose) Supporting my work on GitHub Sponsors
- 🌐 Visiting my website at [SethRose.dev](https://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](https://sethrose.dev) | [GitHub](https://github.com/TheSethRose)