Google Cheap Search — official MCP server for serp.cheap

Real-time Google SERP results as an MCP tool: organic results + knowledge graph, with country targeting, language, time filters and pagination. From $0.60 per 1,000 searches (cache hits cost half).

• Tool: google_search
• npm: @serpcheap/mcp · bin: serpcheap-mcp
• Transports: stdio (local, default) and Streamable HTTP (remote, https://mcp.serp.cheap/mcp)

Get an API key at app.serp.cheap.

Quick start

Claude Code

claude mcp add google-cheap-search -e SERPCHEAP_API_KEY=your-key -- npx -y @serpcheap/mcp

Claude Desktop / Cursor / Windsurf (stdio)

{
  "mcpServers": {
    "google-cheap-search": {
      "command": "npx",
      "args": ["-y", "@serpcheap/mcp"],
      "env": { "SERPCHEAP_API_KEY": "your-key" }
    }
  }
}

Remote (Streamable HTTP — no local install)

{
  "mcpServers": {
    "google-cheap-search": {
      "url": "https://mcp.serp.cheap/mcp",
      "headers": { "Authorization": "Bearer your-key" }
    }
  }
}

The remote server is stateless: your key is forwarded per request to the API and never stored.

The google_search tool

Argument	Type	Default	Description
q	string (1–500)	—	The search query.
gl	enum	us	Country: br us gb de fr es it mx ca au jp nl.
hl	string	country native	Result language, BCP-47 style (en, pt-BR).
tbs	enum	all time	Time filter: qdr:h (hour), qdr:d (day), qdr:w (week).
page	int (1–99)	1	Result page, ~10 organic results each.

Returns structured content (same shape as the REST API) and a markdown rendering:

{
  "search": "mount everest",
  "page": 1,
  "knowledgeGraph": { "title": "Mount Everest", "description": "…", "attributes": { } },
  "organic": [
    { "position": 1, "title": "…", "link": "…", "snippet": "…", "sitelinks": [] }
  ],
  "stats": { "balance": 9970, "cost": 6, "cached": false }
}

Configuration

Env var	Default	Description
SERPCHEAP_API_KEY	—	API key. Required for stdio; HTTP fallback when no header is sent.
SERPCHEAP_BASE_URL	https://api.serp.cheap	API base URL override.
SERPCHEAP_TIMEOUT_MS	20000	Upstream request timeout (1000–120000).

CLI

serpcheap-mcp [--stdio | --http] [--host 127.0.0.1] [--port 7100] [-v] [-h]

--http serves Streamable HTTP at /mcp (plus /healthz), stateless JSON-response mode — safe to run behind a load balancer. Per-request auth via Authorization: Bearer or X-API-Key headers.

HTTP-mode security model

• The server never stores user keys; each request's key is forwarded to the API and dropped.
• Request bodies are capped at 1 MB (413 beyond that).
• /mcp is POST-only; GET/DELETE get 405 (no idle SSE streams to pin connections with).
• The SERPCHEAP_API_KEY env fallback is denied to browser-originated requests (any request carrying an Origin header): a malicious web page hitting a self-hosted instance via DNS rebinding cannot spend your key. Browser-based MCP clients are unaffected — they send their own key via headers. Non-browser clients (curl, server-side SDKs) don't send Origin and keep the fallback. If you self-host with a fallback key, still bind to localhost or front it with your own auth: anyone who can reach the port can use the key.

Development

npm install
npm test          # vitest + coverage gate (95% lines / 90% branches)
npm run typecheck
npm run build

This package lives in the serp.cheap monorepo. test/parity.test.ts pins the tool schema to the public API contract (api/src/schemas/search.ts) — contract drift fails CI.