Serp MCP

🚀 SERP MCP Server

Google SERP scraper as a Model Context Protocol (MCP) server with fingerprint rotation.

Sponsored by

Quercle - Stop wasting tokens on junk. Get exactly what your LLM needs.
Web Fetch & Search API that strips navigation, ads, and footers. Handles JS sites. Returns clean, cited content.

✨ Features

• Automatic fingerprint rotation per request
• Request blocking (only www.google.com/search allowed)
• Lite mode for 50% less traffic (organic results only, DEFAULT)
• Full mode extracts: organic results, sitelinks, PAA, related searches, knowledge graph
• Location encoding via protobuf (UULE format)
• Validated country/language codes

📦 Installation

Claude Code

claude mcp add serp-mcp -- uvx serp-mcp

opencode

Add to your ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "serp-mcp": {
      "type": "local",
      "command": ["uvx", "serp-mcp"],
      "enabled": true
    }
  }
}

Manual Usage

# Run with uvx (automatically installs and runs the latest version)
uvx serp-mcp

Development

git clone https://github.com/LiranYoffe/serp-mcp
cd serp-mcp
uv sync
uv run serp-mcp

💻 Usage Examples

search

Search Google and extract SERP data.

Parameters:

• query (required): Search query
• country (default: "us"): Country code (us, uk, fr, de, etc.)
• language (default: "en"): Language code (en, fr, de, es, etc.)
• location (optional): Location for local results (e.g., "New York, NY")
• time_range (optional): Time filter (hour, day, week, month, year)
• autocorrect (default: true): Enable query autocorrection
• page (default: 1): Page number
• lite (default: true): Lite mode (organic results only, 50% less traffic)

Example Usage:

Search for "python tutorial" with default settings
Search for "python tutorial" in France with lite mode
Search for "restaurants" in New York with 7-day time filter

📚 Documentation

Country Codes

Valid ISO 3166-1 alpha-2 codes: us, uk, fr, de, es, it, jp, kr, cn, in, br, etc. (243 codes)

Language Codes

Valid Google language codes: en, fr, de, es, it, pt, ru, ja, ko, zh-cn, zh-tw, ar, hi, etc. (78 codes)

Time Ranges

• hour: Past hour
• day: Past 24 hours
• week: Past week
• month: Past month
• year: Past year

🔧 Technical Details

• Fingerprint Rotation: Automatic browser fingerprint rotation for each request
• MCP Protocol: Model Context Protocol server with stdio transport
• Blocking: All non-Google requests blocked for efficiency

Development

Run Tests

uv run pytest

Regenerate Protobuf

uv run python -m grpc_tools.protoc \
  --python_out=serp_mcp \
  -Iserp_mcp \
  serp_mcp/uule.proto

📄 License

MIT