Serpapi MCP

1# <img src="https://user-images.githubusercontent.com/307597/154772945-1b7dba5f-21cf-41d0-bb2e-65b6eff4aaaf.png" width="30" height="30"/> SerpApi MCP Server
2 
3A Model Context Protocol (MCP) server implementation that integrates with [SerpApi](https://serpapi.com) for comprehensive search engine results and data extraction.
4 
5[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
6[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7[![Install in VS Code](https://img.shields.io/badge/Install%20in-VS%20Code-blue?logo=visualstudiocode)](vscode://mcp/install?serverID=io.github.serpapi/serpapi-mcp)
8 
9## Features
10 
11- **Multi-Engine Search**: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and [more](https://serpapi.com/search-engine-apis)
12- **Engine Resources**: Per-engine parameter schemas available via MCP resources (see Search Tool)
13- **Real-time Weather Data**: Location-based weather with forecasts via search queries
14- **Stock Market Data**: Company financials and market data through search integration
15- **Dynamic Result Processing**: Automatically detects and formats different result types
16- **Flexible Response Modes**: Complete or compact JSON responses
17- **JSON Responses**: Structured JSON output with complete or compact modes
18 
19## Quick Start
20 
21SerpApi MCP Server is available as a hosted service at [mcp.serpapi.com](https://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](https://serpapi.com/dashboard).
22 
23You can configure Claude Desktop to use the hosted server:
24 
25```json
26{
27  "mcpServers": {
28    "serpapi": {
29      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
30    }
31  }
32}
33```
34 
35### Self-Hosting
36```bash
37git clone https://github.com/serpapi/serpapi-mcp.git
38cd serpapi-mcp
39uv sync && uv run src/server.py
40```
41 
42Configure Claude Desktop:
43```json
44{
45  "mcpServers": {
46    "serpapi": {
47      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
48    }
49  }
50}
51```
52 
53Get your API key: [serpapi.com/manage-api-key](https://serpapi.com/manage-api-key)
54 
55## Authentication
56 
57Two methods are supported:
58- **Path-based**: `/YOUR_API_KEY/mcp` (recommended)
59- **Header-based**: `Authorization: Bearer YOUR_API_KEY`
60 
61**Examples:**
62```bash
63# Path-based
64curl "https://mcp.serpapi.com/your_key/mcp" -d '...'
65 
66# Header-based  
67curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'
68```
69 
70## Search Tool
71 
72The 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](https://serpapi.com/search-api).
73Engine parameter schemas are also exposed as MCP resources: `serpapi://engines` (index) and `serpapi://engines/<engine>`.
74 
75The parameters you can provide are specific for each API engine. Some sample parameters are provided below:
76 
77- `params.q` (required): Search query
78- `params.engine`: Search engine (default: "google_light") 
79- `params.location`: Geographic filter
80- `mode`: Response mode - "complete" (default) or "compact"
81- ...see other parameters on the [SerpApi API reference](https://serpapi.com/search-api)
82 
83**Examples:**
84 
85```json
86{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
87{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
88{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
89{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
90{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
91```
92 
93**Supported Engines:** Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and more (see `serpapi://engines`).
94 
95**Result Types:** Answer boxes, organic results, news, images, shopping - automatically detected and formatted.
96 
97## Development
98 
99```bash
100# Local development
101uv sync && uv run src/server.py
102 
103# Docker
104docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp
105 
106# Regenerate engine resources (Playground scrape)
107python build-engines.py
108 
109# Testing with MCP Inspector
110npx @modelcontextprotocol/inspector
111# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"
112```
113 
114## Troubleshooting
115 
116- **"Missing API key"**: Include key in URL path `/{YOUR_KEY}/mcp` or header `Bearer YOUR_KEY`
117- **"Invalid key"**: Verify at [serpapi.com/dashboard](https://serpapi.com/dashboard)  
118- **"Rate limit exceeded"**: Wait or upgrade your SerpApi plan
119- **"No results"**: Try different query or engine
120 
121## Contributing
122 
1231. Fork the repository
1242. Create your feature branch: `git checkout -b feature/amazing-feature`
1253. Install dependencies: `uv install`
1264. Make your changes
1275. Commit changes: `git commit -m 'Add amazing feature'`
1286. Push to branch: `git push origin feature/amazing-feature`
1297. Open a Pull Request
130 
131## License
132 
133MIT License - see [LICENSE](LICENSE) file for details.
134