serpapi/serpapi-mcp

A Model Context Protocol (MCP) server implementation that integrates with SerpApi for comprehensive search engine results and data extraction.

Python 3.13+ MIT License Install in VS Code Install in Cursor

Features

• Multi-Engine Search: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and more
• Engine Resources: Per-engine parameter schemas available via MCP resources (see Search Tool)
• Real-time Weather Data: Location-based weather with forecasts via search queries
• Stock Market Data: Company financials and market data through search integration
• Dynamic Result Processing: Automatically detects and formats different result types
• Flexible Response Modes: Complete or compact JSON responses
• JSON Responses: Structured JSON output with complete or compact modes

Quick Start

SerpApi MCP Server is available as a hosted service at mcp.serpapi.com. In order to connect to it, you need to provide an API key. You can find your API key on your SerpApi dashboard.

You can configure Claude Desktop to use the hosted server:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Self-Hosting

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Configure Claude Desktop:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Get your API key: serpapi.com/manage-api-key

Authentication

Two methods are supported:

• Path-based: /YOUR_API_KEY/mcp (recommended)
• Header-based: Authorization: Bearer YOUR_API_KEY

Examples:

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

# Header-based  
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

Search Tool

The MCP server has one main Search Tool that supports all SerpApi engines and result types. You can find all available parameters on the SerpApi API reference. Engine parameter schemas are also exposed as MCP resources: serpapi://engines (index) and serpapi://engines/<engine>.

The parameters you can provide are specific for each API engine. Some sample parameters are provided below:

• params.q (required): Search query
• params.engine: Search engine (default: "google_light")
• params.location: Geographic filter
• mode: Response mode - "complete" (default) or "compact"
• ...see other parameters on the SerpApi API reference

Examples:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}

Supported Engines: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and more (see serpapi://engines).

Result Types: Answer boxes, organic results, news, images, shopping - automatically detected and formatted.

Development

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Troubleshooting

• "Missing API key": Include key in URL path /{YOUR_KEY}/mcp or header Bearer YOUR_KEY
• "Invalid key": Verify at serpapi.com/dashboard
• "Rate limit exceeded": Wait or upgrade your SerpApi plan
• "No results": Try different query or engine

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Install dependencies: uv install
4. Make your changes
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

License

MIT License - see LICENSE file for details.