# SerpPortal SERP API — MCP server for LLMs

> The Model Context Protocol server exposes the SERP API to AI agents (Claude Desktop, IDEs, custom
> agents) as callable tools. It wraps the same /v1 REST surface and authenticates with a normal API
> key. Point it at the hosted service or a local instance.

- SERP API base URL: https://serp-api.hoangha.shop
- Auth: a normal API key, `sk_live_...`.

## Install & run

The MCP server ships as an optional dependency group of the SERP API package.
```
pip install -e '.[mcp]'
export SERP_API_BASE_URL=https://serp-api.hoangha.shop
export SERP_API_KEY=sk_live_...
serp-api-mcp            # stdio transport
# or: python -m serp_api.mcp_server
```

## Tools

- `serp_search(keyword, location?, gl?, hl?, uule?, lat?, lon?, radius?, device="desktop", async_mode=true, stop_domain?, capture_aio?, google_domain?, tbs?, tbm?, safe?, nfpr=false, filter?, lr?, cr?, ludocid?, lsig?, kgmid?, si?, ibp?, uds?, color_scheme?, no_cache=false, pages?)`: run a Google SERP search. `pages` (1-10) is the crawl depth — unset means the full ~100 results; `pages=1` is a single navigation and by far the fastest. Async by default; returns {job_id, status, cached, ...}. The AI Overview is captured by default; pass capture_aio=false to skip it for a faster crawl. Supports all Google query knobs (tbs, tbm, safe, nfpr, filter, lr, cr, google_domain, color_scheme) plus the opaque entity identifiers (ludocid, lsig, kgmid, si, ibp, uds). lat/lon (+ optional radius) target a point instead of a named location and cannot be combined with location or uule.
- `serp_get_results(job_id, output="serpapi", start=0)`: fetch a job (output = serpapi | json | html); `start` is the result offset over the already-crawled full depth. Poll while running.
- `serp_usage()`: report the API key's tier, monthly quota, usage this month, and remaining quota.

Typical agent loop: call `serp_search` to submit, then `serp_get_results(job_id)` until the status is
terminal (done | partial | failed). Use `serp_usage` to stay within quota.

## Connect Claude Desktop

Add the server to `claude_desktop_config.json` and restart Claude Desktop; the tools then appear to
the model automatically.
```
{
  "mcpServers": {
    "serp-api": {
      "command": "serp-api-mcp",
      "env": {
        "SERP_API_BASE_URL": "https://serp-api.hoangha.shop",
        "SERP_API_KEY": "sk_live_..."
      }
    }
  }
}
```

The config file holds a live API key. Protect it like any credential and use a dedicated key you can
revoke independently.