gemini-search-mcp (cn fork)

Free MCP server for web search powered by Google AI Mode (Gemini). Forked from Sophomoresty/gemini-search-mcp with adaptations for non-US IP environments.

What's different from upstream

Related MCP server: Apeiron

Quick start

# 1. Install
pip install -e .

# 2. Prime a persistent Chrome profile (headed, manual CAPTCHA solve if prompted)
python scripts/prime_chrome_v2.py --profile-dir ~/.cache/gemini-search/chrome-profile

# 3. Add to your MCP config (Claude Desktop, Hermes, etc.)

MCP server config:

{
  "mcpServers": {
    "gemini-search": {
      "command": "python",
      "args": ["-m", "gemini_search_mcp"],
      "env": {
        "GEMINI_SEARCH_USER_DATA_DIR": "~/.cache/gemini-search/chrome-profile",
        "HEADLESS": "0",
        "BROWSER_CHANNEL": "chrome"
      }
    }
  }
}

Requirements for AI Mode (full quality)

Google AI Mode is gated by 3 things:

1. headed Chrome window — --headless=new triggers /sorry/ CAPTCHA

2. persistent profile — fresh profiles get 91KB JS shell instead of 360KB token page

3. US-region IP — non-US IPs see "AI Mode is not currently available on your device or account"

When all three are met, the engine auto-detects AI Mode availability during _warmup and uses it. When any fails, it falls back to organic SERP extraction (still 5 results with links, just not AI-synthesized).

Headless fallback

Set HEADLESS=1 to run without a visible window. The engine will:

• Use the persistent profile (still required)

• Detect that AI Mode is blocked (91KB shell, no data-srtst token)

• Fall back to extracting top 5 organic Google results from the rendered DOM

Answer quality is lower (snippet concat vs Gemini synthesis) but stable and fast.

MCP tools

Architecture

Agent calls web_search("query")
  → Chrome Runtime.evaluate (CDP via websockets)
    → _warmup: navigate to google.com/search?q=hello (no udm)
      → builds cookie session (NID, AEC, SNID)
    → Probe AI Mode: fetch google.com/search?q=test&udm=50
      → if has data-srtst token → AI Mode enabled
      → if 91KB shell or /sorry/ → organic fallback
    → ask():
      [AI Mode path]
      → fetch AI Mode URL (udm=50&aep=1&ntc=1)
      → extract data-srtst, data-xsrf-folwr-token, data-garc, etc.
      → POST to /async/folwr endpoint
      → parse .pTRUV + .n6owBd blocks from HTML
      [Organic path]
      → navigate to /search?q=...
      → extract top 5 div.g blocks from rendered DOM

Files

• gemini_search/engine.py — Chrome CDP engine, dual strategy

• gemini_search_mcp/ — FastMCP server exposing web_search + ask tools

• gemini_search/server.py — OpenAI-compatible API server (gemini-search --port 8080)

• scripts/prime_chrome_v2.py — headed CAPTCHA priming helper

• scripts/uc_google_probe.py — undetected-chromedriver probe (for advanced CAPTCHA bypass)

• scripts/windows_chrome_profile_probe.py — Windows-specific two-phase profile verifier

• compare_v2.py — Gemini Search vs Tavily comparison harness (13 queries)

• generate_report_v2.py — generates markdown report from results JSON

License

MIT (same as upstream)