gemini-search-mcp

What is this

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.

Think of it as a free, unlimited alternative to Grok MCP / Tavily / SerpAPI, backed by Google's search index.

Features

• Free: No API key, no subscription, no quota
• Unlimited: 60+ requests/min with zero rate limiting
• Google quality: Powered by Gemini + Google Search (grounded in real web results)
• MCP native: Works with Claude Desktop, Claude Code, Cursor, Windsurf, Cline
• Also ships OpenAI API: /v1/chat/completions for non-MCP clients
• Fast: ~1.5s average response time

Quick Start

bashCopy code
pip install -e .

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

MCP Server (for AI agents)

bashCopy code
gemini-search-mcp

OpenAI-compatible API

bashCopy code
gemini-search --port 8080

MCP Integration

Claude Code

bashCopy code
claude mcp add gemini-search -- gemini-search-mcp

Claude Desktop

Add to claude_desktop_config.json:

jsonCopy code
{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "args": [],
      "env": {
        "CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Cursor / Windsurf

Same pattern — point to gemini-search-mcp as an stdio MCP server.

MCP Tools

Examples

Copy code
web_search("latest AI regulation news 2026")
→ "The EU AI Act enforcement began on June 1, 2026, requiring..."

web_search("Bitcoin price today")
→ "As of June 30, 2026, Bitcoin is trading at $59,687 USD..."

ask("what is 1847 * 293")
→ "541171"

OpenAI API Usage

bashCopy code
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-search","messages":[{"role":"user","content":"What happened in the news today?"}]}'

Environment Variables

Persistent Chrome profile / CAPTCHA priming

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:

bashCopy code
# 1) Visible first run: solve CAPTCHA manually if Google asks.
gemini-search --no-headless --user-data-dir "$HOME/.local/share/gemini-search-mcp/chrome-profile"

# 2) Later runs: reuse the same cookies headlessly.
GEMINI_SEARCH_USER_DATA_DIR="$HOME/.local/share/gemini-search-mcp/chrome-profile" gemini-search

For Windows-side validation from WSL, run the probe with Windows Python through PowerShell so it launches Windows Chrome:

powershellCopy code
$profile = Join-Path $env:TEMP 'gemini-search-mcp-persistent-profile'
python .\scripts\windows_chrome_profile_probe.py `
  --profile-dir $profile `
  --mode two-phase `
  --out .\headless-reuse-result.json

Success evidence is ok=true and stages.headless_reuse.captcha=false in the JSON output.

undetected-chromedriver CAPTCHA probe

When a normal Chrome subprocess gets a Google /sorry/ CAPTCHA, install the optional backend and run the reusable probe against google.com.hk:

bashCopy code
pip install -e '.[undetected]'
python scripts/uc_google_probe.py \
  --proxy socks5://127.0.0.1:7897 \
  --out-json uc-probe.json

Use the backend only when the probe reports ok=true, captcha=false, and successful_for_engine_integration=true.

bashCopy code
gemini-search \
  --browser-backend undetected \
  --proxy-server socks5://127.0.0.1:7897 \
  --chromedriver-path /path/to/chromedriver \
  --no-headless

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

How It Works

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.

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.

Copy code
Agent calls web_search("query")
  → Chrome Runtime.evaluate(fetch)
    → Google Search AI Mode (token extraction + folwr endpoint)
      → Parse answer from HTML response
        → Return to agent

Comparison

Docker

bashCopy code
docker compose up -d

Requirements

• Python 3.10+
• Chrome, Edge, or Chromium
• Runtime dependencies from pyproject.toml
• Optional: undetected-chromedriver and selenium via pip install -e '.[undetected]'

Limitations

• Requires Chrome/Edge/Chromium installed
• No conversation memory between requests
• Answer extraction relies on Google's DOM structure (may break on updates)
• Streaming is chunked, not per-token

Acknowledgments

• GenericAgent — 本项目核心开发依仗 GA 提供的 AI 能力
• linux.do community

License

MIT