SkillAgentSearch skills...

gsearch

Real Google Search for AI agents, over MCP. Self-hosted, no API key. Real URLs, AI Overview and People also ask as typed JSON. Uses a real Firefox (Camoufox) on your IP or any proxy.

Install / Use

claude mcp add RayenMlayeh -- npx -y github:RayenMlayeh/gsearch

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

84/100

Supported Platforms

Claude Code
Claude Desktop
Cursor

Our assessment of gsearch

gsearch scores 84/100 on our quality scale, 602nd of 947 AI & Machine Learning skills we index.

Its MCP Server is 22 KB long, well organised into 16 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.

It has 10 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
4/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 13 days ago, so gsearch is actively maintained.
  • Our last check on 2026-11-10 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

gsearch compared with similar skills

All 4 of these similar skills score higher than gsearch; compare them before choosing.

SkillScoreStarsUpdatedFormat
gsearch (this skill)by RayenMlayeh841013d agoMCP Server
claude-memby thedotmack100117.6ktodayCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md

Frequently asked questions

How do I install gsearch?
Run claude mcp add RayenMlayeh -- npx -y github:RayenMlayeh/gsearch. The install tabs above show the steps for each supported agent.
Which AI agents does gsearch work with?
It is written for Claude Code, Claude Desktop and Cursor, as a MCP Server file. Other agents that read the same format can often use it too.
Is gsearch safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is gsearch still maintained?
The repository was last updated 13 days ago, so gsearch is actively maintained.
<p align="center"> <img src="docs/assets/banner.svg" alt="gsearch: Google Search for AI agents. Real results as clean JSON, over MCP." width="100%"> </p> <!-- mcp-name: io.github.RayenMlayeh/gsearch --> <p align="center"> <a href="https://github.com/RayenMlayeh/gsearch/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/RayenMlayeh/gsearch/ci.yml?branch=main&label=tests&style=for-the-badge" alt="Tests"></a> <a href="https://pypi.org/project/gsearch-agent/"><img src="https://img.shields.io/pypi/v/gsearch-agent?color=4285F4&style=for-the-badge" alt="PyPI"></a> <img src="https://img.shields.io/badge/python-3.12%2B-34A853?style=for-the-badge" alt="Python 3.12+"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-FBBC05?style=for-the-badge" alt="MIT license"></a> <img src="https://img.shields.io/badge/MCP-server-EA4335?style=for-the-badge" alt="MCP server"> </p> <p align="center"> <b><a href="#-quick-start">Quick start</a></b> · <b><a href="#-how-it-compares">How it compares</a></b> · <b><a href="#-what-your-agent-gets">What you get</a></b> · <b><a href="#-how-it-works">How it works</a></b> · <b><a href="#-proxies">Proxies</a></b> · <b><a href="#-performance">Performance</a></b> · <b><a href="#-faq">FAQ</a></b> </p> <h3 align="center">Real Google Search for your AI agent. No API key. Self-hosted. Over MCP.</h3>

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

<p align="center"><img src="docs/assets/demo.gif" alt="A live google_search call over MCP: python 3.14 release notes, 9 results in 1.5 s, every link resolved to its real URL, plus People also ask" width="100%"></p> <p align="center"><sub>A real, live call on a home IP with a warm session, rendered from the recorded result; the wait shown is the measured time. <a href="docs/assets/demo.mp4">MP4</a></sub></p>

🚀 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
<details> <summary><b>Claude Desktop, Cursor and other MCP clients</b></summary>

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.

</details>

[!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

<p align="center"><img src="docs/assets/compare.svg" alt="How gsearch compares with paid SERP APIs, other search indexes, free engine MCP servers and Playwright Chromium Google MCP servers" width="100%"></p> <details> <summary><b>The same comparison as text</b></summary>

| | gsearch | SerpApi, Bright Data | Brave, Tavily, Exa | DuckDuckGo, SearXNG MCPs | Playwright + Chromium Google MCPs | |---|---|---|---|---|---| | Google's own results | ✅ | ✅ | ❌ their own index | ❌ / depends on the instance | ✅ | | API key or account | none | required | required | none | none | | Cost | free (+ your proxy, optional) | per query | usage-based plans | free | free | | Runs on your machine | ✅ | ❌ hosted | ❌ hosted | ✅ | ✅ | | AI Overview, People also ask | ✅ | ✅ (SerpApi) | ❌ | ❌ | varies | | Google's redirect links resolved to real URLs | ✅ | ✅ | n/a | n/a | varies | | Blocks reported as errors with a retry time | ✅ | n/a | n/a | varies | varies | | Terms-of-Service risk is yours | yes (Legal) | the provider's | no | low | yes |

</details>

<sub>"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.</sub>

<p align="center"><img src="docs/assets/results.svg" alt="Results: 29 of 29 searches served with 0 CAPTCHAs on a home IP, 0.6 s per search on a warm session, 2 s for a search plus the text of its top 3 pages, 0.6 MB per search on a clean proxy IP" width="100%"></p> <p align="center"><sub> Measured in October and November 2026: <a href="docs/findings/F-0016-home-ip-warm-search-and-read-top.md">F-0016</a>, <a href="docs/findings/F-0014-eh1-hybrid-session-reuse.md">F-0014</a>, <a href="docs/findings/F-0006-fixture-provenance-and-serp-anatomy.md">F-0006</a>, <a href="docs/findings/F-0011-goto-resolution-leak-and-fix.md">F-0011</a>, <a href="docs/findings/F-0012-headless-vs-headed-fingerprint.md">F-0012</a>, <a href="docs/findings/F-0001-cold-start-chrome-vs-camoufox.md">F-0001</a>; 14 s and 0.6 MB on a clean proxy IP: <a href="docs/findings/F-0015-b1-residential-proxy-benchmark.md">F-0015</a>. Flagged proxy pools are slower: see <a href="#-performance">Performance</a>. </sub></p>

✨ Why gsearch

<p align="center"><img src="docs/assets/why.svg" alt="Same IP: plain HTTP gets 0 results, automated Chrome gets a CAPTCHA 2 of 2 times, gsearch is served 29 of 29" width="100%"></p>

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

<p align="center"><img src="docs/assets/what-you-get.svg" alt="Each part of a Google results page and the JSON field it becomes" width="100%"></p>

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

<p align="center"><img src="docs/assets/search.svg" alt="gsearch search output" width="820"></p>

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

<p align="center"><img src="docs/assets/captcha.svg" alt="A CAPTCHA returned as a structured error" width="820"></p> <details> <summary><b>Every field explained</b></summary>

| Field | What it holds | |---|---| | organic[].url | The real destination of each result, with resolve_links; otherwise null, and link goes to fetch_page. | | organic[].title, snippet, date, domain, display_url | What the result shows, as text. link keeps the exact link Google served. | | organic[].sitelinks, source_meta | A result's sub-links, and what Google shows instead of a URL on forum and video results (2 years ago). | | ai_overview | The AI Overview text and its sources, when Google shows one. | | people_also_ask, related_searches | The questions and related queries on the page. | | ads | Text ads, when the market serves them. | | pagination | Current page and next page. Ask for more results with page. | | meta.untrusted_content | Always true: every string is third-party web text (see prompt injection). |

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.

</details>

🔍 How it works

<p align="center"><img src="docs/assets/how-it-works.svg" alt="One search: agent asks, fresh IP, real Firefox, clean JSON, all closed" width="100%"></p>
  • 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

<p align="center"><img src="docs/assets/proxies.svg" alt="Rotating residential, static or VPS proxies, or no proxy; any format" width="100%"></p>
# 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

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars10
CategoryAI
Updated13d ago
Forks2

Languages

Python

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info