gsearch 0.1.0

First public release: real Google Search for AI agents, over MCP.

Install

uv tool install gsearch-agent        # or: pipx install gsearch-agent
gsearch setup                        # downloads the browser once (~1 GB), prints your MCP config
claude mcp add gsearch --scope user -- gsearch-mcp

What's in it

• MCP server with two tools: google_search (query, page, lang, country, time range, site) and google_search_status.
• Typed JSON: organic results with every Google /goto link resolved to its real URL, the AI Overview, People also ask, related searches, ads and pagination. Every string is flagged as untrusted web content.
• Clear errors: blocks come back as structured errors (captcha, rate_limited, …) with retry_after_s, never as empty results.
• Real browser: Camoufox (a hardened Firefox) runs Google's page as it is. gsearch never forges tokens and ships no CAPTCHA solver.
• Your own IP, by default: at most 20 searches an hour and 150 a day.
• Any proxy: rotating or static; HTTP, HTTPS or SOCKS5; any common format. Every byte is metered against a hard data limit.
• CLI and Python library: gsearch search, gsearch parse, gsearch schema, gsearch setup, and SearchClient.

Tested

• Windows, live.
• Linux and Windows offline in CI (Python 3.12–3.14).
• macOS and live Linux servers are untested: help wanted, #4 and #5.

Read the legal section before running live searches.