gsearch

Quick start · How it compares · What you get · How it works · Proxies · Performance · FAQ

Real Google Search for your AI agent. No API key. Self-hosted. Over MCP.

Your agent calls google_search and gets Google's actual results page as typed JSON: every result with its title, snippet and site, plus Google's answer boxes (sports results, top stories, videos), the AI Overview, People also ask and related searches. A real Firefox (Camoufox) runs Google's page as it is, on your own IP or through any proxy you already have.

Why: plain HTTP gets a JavaScript wall, automated Chrome got a CAPTCHA 2 out of 2 times in our test, and Google's official Custom Search API closes on 1 January 2027. Other search MCP servers either aren't Google's index (Brave, Tavily, Exa, DuckDuckGo) or charge per query (SerpApi, Bright Data).

A real, live call on a home IP with a warm session, rendered from the recorded result; the wait shown is the measured time. MP4

🚀 Quick start

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 # or any MCP client, below

Then just ask: *"Search Google for what asyncio is and give me the top three links"*, *"What do people also ask about asyncio?"*, *"Find asyncio pages on python.org from the past year."*, *"Search for the asyncio docs and summarize the first result."*

Without a proxy, gsearch uses your own IP, at most 20 searches an hour. For more, add a proxy in any format:

claude mcp add gsearch --scope user -e GSEARCH_PROXY="gate.example.com:7000:user-sid-{sid}:password" -e GSEARCH_DATA_LIMIT_MB=1000 -- gsearch-mcp

Claude Desktop, Cursor and other MCP clients

gsearch setup prints this block with the full path of gsearch-mcp filled in. Use the full path if your client doesn't find the command.

{

"mcpServers": { "gsearch": { "command": "gsearch-mcp", "env": { "GSEARCH_PROXY": "optional, any format", "GSEARCH_DATA_LIMIT_MB": "1000" } } } }

Claude Desktop: claude_desktop_config.json. Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json in a project.

No install, with uv: use "command": "uvx", "args": ["gsearch-agent"], after fetching the browser once with uvx --from gsearch-agent gsearch setup.

Settings in a file: put them in a .env (see .env.example) and set GSEARCH_ENV_FILE to its absolute path instead.

[!NOTE]

Automated access to Google Search may breach Google's Terms of Service. Read

Legal and responsible use before running live searches.

🆚 How it compares

The same comparison as text

"Varies": we did not test those projects. Our only Chromium measurement is F-0001: Playwright Chrome was sent to a CAPTCHA 2 of 2 times on an IP where gsearch was served. Read Legal before running live searches.

Measured in October and November 2026: F-0016 , F-0014 , F-0006 , F-0011 , F-0012 , F-0001 ; 14 s and 0.6 MB on a clean proxy IP: F-0015 . Flagged proxy pools are slower: see Performance .

✨ Why gsearch

Google's official search API is closed to new customers and shuts down on 1 January 2027 (F-0005). gsearch is built for AI agents instead:

• 🦊 A real browser, not a scraper. Camoufox, a hardened Firefox, runs Google's page as it is, with a real-device fingerprint and a locale that matches its IP.
• 🔗 Real pages. Google hides result links behind /goto redirects. fetch_page follows one to the page it points to when the agent reads it; resolve_links resolves them all up front instead, and read_top returns the top pages' text with the results, in one call.
• 🤖 Built for agents. One MCP server: search, page reading and status, typed JSON. Blocks come back as clear errors with retry_after_s, never as empty results, and every string is flagged as untrusted web content.
• 🌍 Any proxy, any format. Rotating residential, static VPS or datacenter lists, HTTP, HTTPS or SOCKS5, in any common layout. Every byte is counted, with a hard data limit.
• 🎯 Nothing to tune. Two settings. Everything else is fixed to what worked best in testing.
• 📊 Honest numbers. Every claim in this README links to a write-up of how it was measured.

📦 What your agent gets

Real output from a saved results page (offline demo mode, where url stays null; a live search fills it):

A block is never an empty list. It comes back as an error that says what happened and how long to wait:

Every field explained

Error codes: captcha, soft_block, hard_block, consent_wall, js_gate, rate_limited, parse_drift, network, proxy, backend_unavailable, invalid_request. The full JSON Schema is in serp.schema.json.

🔍 How it works

• Like a person. A visible window, because headless sessions were challenged far more often on proxy IPs (F-0015). The query is typed into the address bar. WebRTC is off, so your own IP can't leak around the proxy.
• Never forged. gsearch never generates or alters Google's tokens: the browser runs the page as it is.
• Cheap links. Links are resolved only when asked, on the same IP without the search session's cookies, with a TLS fingerprint matching the browser's (F-0011, F-0013).
• Runs on servers. On a Linux machine without a screen, the browser uses a virtual display automatically (sudo apt install xvfb).

🌍 Proxies

# rotating residential: {sid}, or your provider's sid-…, session-…, sessid-… part, gives a new IP per search

GSEARCH_PROXY=gate.example.com:7000:user-country-us-sid-{sid}:password

static proxies (VPS, datacenter, ISP): one or many, separated by commas, spaces or new lines

GSEARCH_PROXY=socks5://user:password@203.0.113.10:1080, http://203.0.113.11:3128

or a file with one proxy per line

GSEARCH_PROXY=/path/to/proxies.txt

• Rotating: a new IP and a new browser for every search, up to 3 at once. A blocked IP is replaced, up to 4 IPs per search. country-xx or cc-xx in the login is checked, and exits elsewhere are dropped.
• Static: each IP keeps one warm session, and the IPs take turns. Each IP has its own budget (20 searches