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](https://serpapi.com/search-api).
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](https://serpapi.com/search-api)

**Examples:**

```json
{"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.

Interactive UI (MCP Apps)

The default search tool returns JSON and is unchanged. For hosts that support the MCP Apps extension (SEP-1865), two opt-in tools render results as an interactive UI directly in the conversation, so the bulk SERP JSON never enters the model's context window:

• search_table: organic results as a sortable, searchable table.
• search_dashboard: summary metrics, a source-breakdown chart, and a results table with a click-to-expand detail panel.

Both accept the same params as search. Hosts that don't support MCP Apps simply ignore these tools.

Preview them locally without an MCP host:

uv run fastmcp dev apps src/server.py

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.