SerpApi MCP Server

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

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 (default): Structured JSON output with complete or compact modes
• Markdown Responses: Cut token usage by 50% on average and by more than 90% for APIs with complex nested JSON.
• Interactive UI (MCP Apps): Opt-in search_table and search_dashboard tools that render results as an interactive UI in supporting hosts
• Claude Desktop Extension: One-click local install from an MCP Bundle (.mcpb), see below

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

You can also add the hosted server to these MCP clients:

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex

codex mcp add serpapi --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

Claude Desktop Extension (MCP Bundle)

For a local, one-click install, download the .mcpb bundle from the latest release (or build it as below) and open it with Claude Desktop (or drop it onto Settings → Extensions). Claude Desktop asks for your SerpApi API key during install, stores it as a sensitive setting, and runs the server locally over stdio. The bundle uses the MCPB uv runtime: it ships only the source, pyproject.toml and uv.lock, and Claude Desktop provisions Python and the locked dependencies with uv at install time, so nothing is vendored and one bundle works on macOS, Windows and Linux.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Everything bundle-related lives in mcpb/, plus .mcpbignore at the project root. The build regenerates the engine schemas from the SerpApi Playground (--no-rebuild-engines bundles engines/ from the working tree instead), validates mcpb/manifest.json, packs the git-tracked files minus .mcpbignore with the manifest at the bundle root, then installs it into a temp dir and starts it over stdio to make sure it works (--no-smoke skips that last step). The bundle is only built at release time: pushing a v<version> tag runs the release workflow, which runs the test suite and then deploys the hosted server, publishes the MCP Registry entry, and builds the bundle and attaches it to the GitHub release. Pull requests run the manifest and stdio entry point tests in tests/test_mcpb.py but do not pack a bundle.

The same stdio entry point works with any local MCP host that launches servers as a subprocess:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_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
• params.output: Response format; omit for JSON (default), or set to "md" for Markdown
• mode: Response mode; "compact" removes metadata from JSON, while Markdown is returned unchanged
• ...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"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

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

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: bump the version in pyproject.toml, server.json and mcpb/manifest.json, then tag it.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v1.0.2 && git push origin v1.0.2

# 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.