Scrapebadger MCP

🚀 ScrapeBadger MCP Server

Enable AI agents to access Twitter/X data via the Model Context Protocol.

🚀 Quick Start

1. Get Your API Key

Sign up at scrapebadger.com and obtain your API key.

2. Install

# Using uvx (recommended - no installation needed)
uvx scrapebadger-mcp

# Or install globally with pip
pip install scrapebadger-mcp

# Or with uv
uv tool install scrapebadger-mcp

3. Configure Your AI Client

Claude Desktop

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "scrapebadger": {
      "command": "uvx",
      "args": ["scrapebadger-mcp"],
      "env": {
        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "scrapebadger": {
      "command": "uvx",
      "args": ["scrapebadger-mcp"],
      "env": {
        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "scrapebadger": {
      "command": "uvx",
      "args": ["scrapebadger-mcp"],
      "env": {
        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
      }
    }
  }
}

VS Code with Copilot

Add to your VS Code settings (.vscode/mcp.json):

{
  "mcpServers": {
    "scrapebadger": {
      "command": "uvx",
      "args": ["scrapebadger-mcp"],
      "env": {
        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
      }
    }
  }
}

4. Start Using It!

Once configured, simply ask your AI to fetch Twitter data, for example:

• "Get the profile of @elonmusk"
• "Search for tweets about AI agents"
• "What's trending on Twitter right now?"
• "Find the top 10 Python developers on Twitter"

✨ Features

ScrapeBadger MCP Server is a Model Context Protocol (MCP) server. It allows AI assistants such as Claude, ChatGPT, Cursor, Windsurf, and other MCP-compatible clients to access Twitter/X data through the ScrapeBadger API.

With this MCP server, your AI can:

• Get Twitter user profiles, followers, and following lists.
• Search and retrieve tweets.
• Access trending topics globally or by location.
• Explore Twitter lists and communities.
• Search for places and geolocated content.

📦 Installation

The installation methods are as follows:

# Using uvx (recommended - no installation needed)
uvx scrapebadger-mcp

# Or install globally with pip
pip install scrapebadger-mcp

# Or with uv
uv tool install scrapebadger-mcp

💻 Usage Examples

Basic Usage

{
  "mcpServers": {
    "scrapebadger": {
      "command": "uvx",
      "args": ["scrapebadger-mcp"],
      "env": {
        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
      }
    }
  }
}

Advanced Usage

{
  "mcpServers": {
    "scrapebadger": {
      "command": "uvx",
      "args": ["scrapebadger-mcp"],
      "env": {
        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
      }
    }
  }
}

📚 Documentation

Available Tools

The MCP server provides 17 tools organized into categories:

User Tools

Tweet Tools

Trend Tools

Geo Tools

List Tools

Community Tools

Example Conversations

Research a Twitter Account

You: Get the profile and recent tweets from @sama Claude: I'll fetch Sam Altman's Twitter profile and recent tweets. Uses get_twitter_user_profile and get_twitter_user_tweets

Sam Altman (@sama)
- 3.2M followers, 1,847 following
- Bio: "ceo of openai"
- Joined: December 2008

Recent tweets:
1. "excited to share..." (245K likes)
2. "the future of ai..." (180K likes)
...

Monitor Trending Topics

You: What's trending in tech on Twitter today? Claude: I'll check the current trending topics. Uses get_twitter_trends with category="news"

Top Tech Trends:
1. #GPT5 - 125,000 tweets
2. Apple Vision Pro - 89,000 tweets
3. #AGI - 45,000 tweets
...

Competitive Analysis

You: Compare the Twitter engagement of Stripe, Square, and PayPal Claude: I'll gather data on all three companies' Twitter profiles. Uses get_twitter_user_profile for each company

| Company | Followers | Following | Engagement Rate |
|---------|-----------|-----------|-----------------|
| Stripe  | 892K      | 1,245     | 2.3%           |
| Square  | 1.2M      | 567       | 1.8%           |
| PayPal  | 2.1M      | 234       | 0.9%           |

Configuration Options

Environment Variables

Using with Docker

FROM python:3.12-slim

RUN pip install scrapebadger-mcp

ENV SCRAPEBADGER_API_KEY=your_key_here

CMD ["scrapebadger-mcp"]

Using with Python Directly

# Set your API key
export SCRAPEBADGER_API_KEY="sb_live_your_key_here"

# Run the server
python -m scrapebadger_mcp.server

Error Handling

The MCP server handles common errors gracefully:

🔧 Technical Details

Setup

# Clone the repository
git clone https://github.com/scrape-badger/scrapebadger-mcp.git
cd scrapebadger-mcp

# Install dependencies
uv sync --dev

# Set your API key
export SCRAPEBADGER_API_KEY="sb_live_your_key_here"

Running Locally

# Run the MCP server directly
uv run python -m scrapebadger_mcp.server

# Or use the CLI
uv run scrapebadger-mcp

Testing

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/scrapebadger_mcp

Code Quality

# Lint
uv run ruff check src/

# Format
uv run ruff format src/

# Type check
uv run mypy src/

📄 License

This project is under the MIT License. See LICENSE for details.

📚 Support

• Documentation: docs.scrapebadger.com
• Issues: GitHub Issues
• Email: support@scrapebadger.com
• Discord: Join our community

Made with love by ScrapeBadger