ScrapeBadger

[ScrapeBadger]

ScrapeBadger MCP Server

[PyPI version] [Python versions] [License] [MCP Compatible]

Give your AI agents access to Twitter/X data, Google Search, Yelp businesses, GitHub repositories and AutoScout24 listings via the Model Context Protocol

What is this?

ScrapeBadger MCP Server is a Model Context Protocol (MCP) server that enables AI assistants like Claude, ChatGPT, Cursor, Windsurf, and other MCP-compatible clients to access Twitter/X data, Google Search results, Yelp business search, GitHub repository detail and AutoScout24 listing detail 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
• Search Google and read the structured results page, including People Also Ask answers
• Search Yelp businesses in the US and Canada in Yelp's own order, with ads kept separate
• Read a public GitHub repository: README, root files, latest commit and statistics
• Read a full AutoScout24 vehicle listing: specifications, equipment, photos and seller data

Quick Start

1. Get Your API Key

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

2. Install

# Using uvx (recommended - no installation needed)uvx scrapebadger-mcp
# Or install globally with pippip install scrapebadger-mcp
# Or with uvuv tool install scrapebadger-mcp

3. Configure Your AI Client

Claude Desktop

Add 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:

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

"Search Google for 'are noise cancelling headphones worth it' and answer the People Also Ask questions"

Available Tools

The MCP server provides 17 tools organized into categories:

User Tools

Tweet Tools

Trend Tools

Geo Tools

List Tools

Community Tools

Google Tools

search_google takes q, gl, hl, start, location, ai_overview and expand_related_questions. Google loads a People Also Ask answer only when the question is clicked, so by default related_questions holds the questions without answers. expand_related_questions: true opens every question the page shows (usually four) and a number N opens the first N; each answered question then carries text_blocks and references. Each answered question costs one more search (credits = 20 x (1 + answered)), and a question whose answer does not come back is not billed. See the Google web search docs.

Yelp, GitHub repository and AutoScout24 listing tools

These tools return the API response unchanged, so every native field stays available. See the Yelp, GitHub and AutoScout24 docs.

The server lists a tool only while ScrapeBadger's live endpoint catalog lists its endpoint, and marks a deprecated or temporarily unavailable endpoint in the tool description. A call to a restricted endpoint returns the API's error and is not billed.

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 tweets2. Apple Vision Pro - 89,000 tweets3. #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 keyexport SCRAPEBADGER_API_KEY="sb_live_your_key_here"
# Run the serverpython -m scrapebadger_mcp.server

Error Handling

The MCP server handles common errors gracefully:

Development

Setup

# Clone the repositorygit clone https://github.com/scrape-badger/scrapebadger-mcp.gitcd scrapebadger-mcp
# Install dependenciesuv sync --dev
# Set your API keyexport SCRAPEBADGER_API_KEY="sb_live_your_key_here"

Running Locally

# Run the MCP server directlyuv run python -m scrapebadger_mcp.server
# Or use the CLIuv run scrapebadger-mcp

Testing

# Run testsuv run pytest
# Run with coverageuv run pytest --cov=src/scrapebadger_mcp

Code Quality

# Lintuv run ruff check src/
# Formatuv run ruff format src/
# Type checkuv run mypy src/

Troubleshooting

"SCRAPEBADGER_API_KEY environment variable is required"

Make sure you've set the API key in your MCP configuration:

{  "env": {    "SCRAPEBADGER_API_KEY": "sb_live_your_key_here"  }}

Server not showing in Claude Desktop

1. Restart Claude Desktop after changing the config
2. Check the config file path is correct for your OS
3. Verify JSON syntax is valid (no trailing commas)

"uvx: command not found"

Install uv first:

# macOS/Linuxcurl -LsSf https://astral.sh/uv/install.sh | sh
# Windowspowershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Rate limit errors

ScrapeBadger has usage limits based on your plan. If you're hitting limits:

1. Reduce request frequency
2. Use pagination with smaller max_results
3. Upgrade your plan at scrapebadger.com

Related Projects

• ScrapeBadger Python SDK - Official Python SDK
• ScrapeBadger Node.js SDK - Official Node.js SDK
• ScrapeBadger API Docs - Full API documentation

Support

• Documentation: docs.scrapebadger.com
• Issues: GitHub Issues
• Email: [email protected]
• Discord: Join our community

License

MIT License - see LICENSE for details.

Made with love by ScrapeBadger