Skip to content
Back to search

gemini-search-mcp

Free MCP server for web search powered by Google AI Mode (Gemini). Unlimited, no API key.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sophomoresty--gemini-search-mcp/badge.svg)](/listings/sophomoresty--gemini-search-mcp)

HTML

<a href="/listings/sophomoresty--gemini-search-mcp"><img src="/api/listings/sophomoresty--gemini-search-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install -e .

# Optional: install the undetected-chromedriver backend for CAPTCHA probes.
pip install -e '.[undetected]'

MCP Server (for AI agents)

gemini-search-mcp

OpenAI-compatible API

gemini-search --port 8080

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 227 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # gemini-search-mcp
  2. <p align="center">
  3. <img src="banner.png" width="700" alt="gemini-search-mcp">
  4. </p>
  5. <p align="center">
  6. <img src="logo.png" width="120" alt="logo">
  7. </p>
  8. <p align="center">
  9. MCP server for web search powered by Google AI Mode (Gemini). Free, unlimited, no API key.
  10. </p>
  11. ## What is this
  12. An MCP server that gives any AI agent (Claude, Cursor, Windsurf, etc.) the ability to search the web in real-time using Google's AI Mode — the same Gemini-powered search that lives in the "AI Mode" tab on Google Search.
  13. Think of it as a free, unlimited alternative to Grok MCP / Tavily / SerpAPI, backed by Google's search index.
  14. ## Features
  15. - **Free**: No API key, no subscription, no quota
  16. - **Unlimited**: 60+ requests/min with zero rate limiting
  17. - **Google quality**: Powered by Gemini + Google Search (grounded in real web results)
  18. - **MCP native**: Works with Claude Desktop, Claude Code, Cursor, Windsurf, Cline
  19. - **Also ships OpenAI API**: `/v1/chat/completions` for non-MCP clients
  20. - **Fast**: ~1.5s average response time
  21. ## Quick Start
  22. ```bash
  23. pip install -e .
  24. # Optional: install the undetected-chromedriver backend for CAPTCHA probes.
  25. pip install -e '.[undetected]'
  26. ```
  27. ### MCP Server (for AI agents)
  28. ```bash
  29. gemini-search-mcp
  30. ```
  31. ### OpenAI-compatible API
  32. ```bash
  33. gemini-search --port 8080
  34. ```
  35. ## MCP Integration
  36. ### Claude Code
  37. ```bash
  38. claude mcp add gemini-search -- gemini-search-mcp
  39. ```
  40. ### Claude Desktop
  41. Add to `claude_desktop_config.json`:
  42. ```json
  43. {
  44. "mcpServers": {
  45. "gemini-search": {
  46. "command": "gemini-search-mcp",
  47. "args": [],
  48. "env": {
  49. "CDP_URL": "http://127.0.0.1:9222"
  50. }
  51. }
  52. }
  53. }
  54. ```
  55. ### Cursor / Windsurf
  56. Same pattern — point to `gemini-search-mcp` as an stdio MCP server.
  57. ## MCP Tools
  58. | Tool | Description |
  59. |------|-------------|
  60. | `web_search(query)` | Search the web and get a synthesized answer grounded in real-time results |
  61. | `ask(prompt)` | General question — AI Mode auto-decides whether to search the web |
  62. ### Examples
  63. ```
  64. web_search("latest AI regulation news 2026")
  65. → "The EU AI Act enforcement began on June 1, 2026, requiring..."
  66. web_search("Bitcoin price today")
  67. → "As of June 30, 2026, Bitcoin is trading at $59,687 USD..."
  68. ask("what is 1847 * 293")
  69. → "541171"
  70. ```
  71. ## OpenAI API Usage
  72. ```bash
  73. curl http://localhost:8080/v1/chat/completions \
  74. -H "Content-Type: application/json" \
  75. -d '{"model":"gemini-search","messages":[{"role":"user","content":"What happened in the news today?"}]}'
  76. ```
  77. | Field | Value |
  78. |-------|-------|
  79. | Base URL | `http://localhost:8080/v1` |
  80. | API Key | anything |
  81. | Model | `gemini-search` |
  82. ## Environment Variables
  83. | Variable | Default | Description |
  84. |----------|---------|-------------|
  85. | `CDP_URL` | (none) | Chrome DevTools URL. If set, connects to existing Chrome instead of launching one |
  86. | `BROWSER_CHANNEL` | `chrome` | Browser to use: `chrome`, `msedge`, `chromium` |
  87. | `HEADLESS` | `1` | Set to `0` to show browser window |
  88. | `GEMINI_SEARCH_USER_DATA_DIR` | (none) | Persistent Chrome profile directory. Reuses cookies across runs and is not deleted on shutdown |
  89. | `GEMINI_SEARCH_CDP_PORT` | `19250` | CDP port used for self-launched Chrome |
  90. | `GEMINI_SEARCH_BROWSER_BACKEND` | `subprocess` | Browser launcher: `subprocess` or `undetected` |
  91. | `GEMINI_SEARCH_PROXY_SERVER` | (none) | Chrome proxy server, e.g. `socks5://127.0.0.1:7897` |
  92. | `GEMINI_SEARCH_CHROMEDRIVER` | (none) | Chromedriver executable used by the `undetected` backend |
  93. ## Persistent Chrome profile / CAPTCHA priming
  94. If Google shows `/sorry/` CAPTCHA for a fresh temporary profile, prime a persistent profile once in a visible Chrome window, then reuse the same directory in headless mode:
  95. ```bash
  96. # 1) Visible first run: solve CAPTCHA manually if Google asks.
  97. gemini-search --no-headless --user-data-dir "$HOME/.local/share/gemini-search-mcp/chrome-profile"
  98. # 2) Later runs: reuse the same cookies headlessly.
  99. GEMINI_SEARCH_USER_DATA_DIR="$HOME/.local/share/gemini-search-mcp/chrome-profile" gemini-search
  100. ```
  101. For Windows-side validation from WSL, run the probe with Windows Python through PowerShell so it launches Windows Chrome:
  102. ```powershell
  103. $profile = Join-Path $env:TEMP 'gemini-search-mcp-persistent-profile'
  104. python .\scripts\windows_chrome_profile_probe.py `
  105. --profile-dir $profile `
  106. --mode two-phase `
  107. --out .\headless-reuse-result.json
  108. ```
  109. Success evidence is `ok=true` and `stages.headless_reuse.captcha=false` in the JSON output.
  110. ## undetected-chromedriver CAPTCHA probe
  111. When a normal Chrome subprocess gets a Google `/sorry/` CAPTCHA, install the optional backend and run the reusable probe against `google.com.hk`:
  112. ```bash
  113. pip install -e '.[undetected]'
  114. python scripts/uc_google_probe.py \
  115. --proxy socks5://127.0.0.1:7897 \
  116. --out-json uc-probe.json
  117. ```
  118. Use the backend only when the probe reports `ok=true`, `captcha=false`, and `successful_for_engine_integration=true`.
  119. ```bash
  120. gemini-search \
  121. --browser-backend undetected \
  122. --proxy-server socks5://127.0.0.1:7897 \
  123. --chromedriver-path /path/to/chromedriver \
  124. --no-headless
  125. ```
  126. Observed on Windows Chrome for Testing 148 through Clash: headed UC passed (`captcha=false` and AI Mode tokens present), while headless UC hit Google `/sorry/`.
  127. ## How It Works
  128. Google rate-limits by TLS fingerprint quality — not by IP. Automated HTTP clients (curl, requests, httpx) get throttled after a few requests. But a real Chrome browser's `fetch()` calls are trusted unconditionally.
  129. This tool runs a single real Chrome tab and executes all queries as `fetch()` inside it over CDP, giving every request an authentic Chrome TLS/HTTP2 fingerprint. Google sees normal browser traffic and applies no rate limits. The optional `undetected` backend still uses the same CDP query path after launch.
  130. ```
  131. Agent calls web_search("query")
  132. → Chrome Runtime.evaluate(fetch)
  133. → Google Search AI Mode (token extraction + folwr endpoint)
  134. → Parse answer from HTML response
  135. → Return to agent
  136. ```
  137. ## Comparison
  138. | | gemini-search-mcp | Grok MCP | Tavily |
  139. |---|---|---|---|
  140. | Cost | **Free** | xAI API key ($) | API key ($) |
  141. | Rate limit | **None** | API quota | API quota |
  142. | Search backend | Google Search | Grok + web | Proprietary |
  143. | Answer quality | Gemini synthesized | Grok synthesized | Extracted snippets |
  144. | Setup | Chrome + CDP | API key | API key |
  145. ## Docker
  146. ```bash
  147. docker compose up -d
  148. ```
  149. ## Requirements
  150. - Python 3.10+
  151. - Chrome, Edge, or Chromium
  152. - Runtime dependencies from `pyproject.toml`
  153. - Optional: `undetected-chromedriver` and `selenium` via `pip install -e '.[undetected]'`
  154. ## Limitations
  155. - Requires Chrome/Edge/Chromium installed
  156. - No conversation memory between requests
  157. - Answer extraction relies on Google's DOM structure (may break on updates)
  158. - Streaming is chunked, not per-token
  159. ## Acknowledgments
  160. - [GenericAgent](https://github.com/lsdefine/GenericAgent) — 本项目核心开发依仗 GA 提供的 AI 能力
  161. - [linux.do](https://linux.do) community
  162. ## License
  163. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.