google-surf-mcp

English | 한국어

Demo only. Actual searches run headless by default (no visible browser). Set SURF_HEADLESS=false to make Chrome visible like in the clip above.

Google search MCP. Browser mode needs no API key. SearchApi is optional.

One MCP replaces three: search + URL fetcher + academic-paper extractor.

• ✅ Actually works (tested 6 free Google search MCPs, all failed)
• ✅ Search + URL + academic PDF extract in one MCP (replaces the search MCP + fetch MCP + academic-search MCP combo)
• ✅ Academic PDFs extracted inline: arxiv, biorxiv, Nature, OpenReview, NeurIPS, JMLR, PMLR, Springer, PubMed (via PMC)
• ✅ search_extract defaults to abstract mode (~1500 chars/result, token-cheap), mode="full" for whole bodies
• ✅ Sponsored ads + knowledge panels dropped (geometric verification, not just text matching)
• ✅ CAPTCHA recovery in 4 modes: OS notification (default) / SURF_HEADLESS=false / SURF_REMOTE_DEBUG / SURF_CLOUD_MODE (fail-fast)
• ✅ Browser mode needs no API key, proxy, or solver

6 tools: search / scholar_search / search_parallel / extract / search_extract / health

What

Plug it into any MCP client and you get Google search as a tool.

No CAPTCHA solver. When CAPTCHA fires on any tool, a Chrome window opens for a human to solve. Each solve preserves the profile's reputation with Google.

First call auto-bootstraps the warm profile. Designed for local use. For headless / serverless environments set SURF_CLOUD_MODE=true (fail-fast on CAPTCHA, worker pool disabled).

Numbers

Measured on a workstation with a 1Gb/s connection.

Stack

• Playwright + persistent Chrome profile
• playwright-extra stealth as a cascade fallback tier
• Multi-strategy SERP parser + geometric verification (drops sponsored / knowledge_panel / related)
• @llamaindex/liteparse for PDF text extraction (PDFium spatial parsing, optional OCR); Mozilla Readability + Turndown for HTML
• Resource-blocked images / media / fonts for speed
• Auto-bootstrap on first call; pool falls back to single-context after repeated warm failures
• Self-healing: runtime parser-strategy reorder (deterministic) + daily cron repair PR (synthesis → optional LLM → triple-gate validation, human review)

Install

Requires Node 18+. Browser mode also requires Google Chrome or Chromium.

npx google-surf-mcp   # actual MCP - register in client config

First tool call auto-bootstraps the warm profile (you may see Chrome open briefly).

Or local clone:

git clone https://github.com/HarimxChoi/google-surf-mcp
cd google-surf-mcp
npm install

If auto-bootstrap fails (rare), run it manually:

npm run bootstrap

Override paths if needed:

CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap

Use with Claude Code

Paste this into your ~/.claude.json:

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"]
    }
  }
}

Restart Claude Code. Done. search, scholar_search, search_parallel, extract, search_extract, health are now available.

For other MCP clients, use the same JSON shape in their config file.

Search providers

Browser search remains the default. SearchApi can be selected as the primary provider or used only when browser search fails.

SURF_SEARCH_PROVIDER controls search and search_parallel. SURF_SCHOLAR_PROVIDER controls scholar_search. SearchApi modes require your own SearchApi account, key, and available credits.

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"],
      "env": {
        "SEARCH_API": "your-searchapi-key",
        "SURF_SEARCH_PROVIDER": "fallback",
        "SURF_SCHOLAR_PROVIDER": "searchapi"
      }
    }
  }
}

Local clone variant:

{
  "mcpServers": {
    "google-surf": {
      "command": "node",
      "args": ["/abs/path/to/google-surf-mcp/build/index.js"]
    }
  }
}

Tools

• search(query, limit?) - single query, ~1.5s in browser mode. Returns title / url / snippet. Sponsored ads + knowledge-panel dropped on the browser path. Results cached 24h (SURF_CACHE_TTL_SEARCH_MS=0 to bypass).
• scholar_search(query, limit?) - Google Scholar search, max 10 papers. Returns authors, publication, year, snippet, citation count, related/version links, and an available full-text link. Supports browser, SearchApi primary, and fallback modes.
• search_parallel(queries[], limit?) - pool of 4 in browser mode, max 10 queries per call. Follows SURF_SEARCH_PROVIDER.
• extract(url, max_chars?, mode?) - fetch a URL, return article content.
  • mode="full" (default): whole body. HTML via Readability, PDFs via liteparse (spatial parsing, multi-column reading order).
  • mode="abstract": ~1500-char survey (PDF page 1 or HTML meta description). Triage relevance before paying for full text.
  • mode="metadata": PDF page count only.
  • Response: content, title, excerpt, length, is_pdf, page_count, extraction_quality. Failures return { error }, never throw.
• search_extract(query, limit?, max_chars?, mode?) - search + parallel extract in one call. Default mode="abstract" returns SERP enriched with ~1500-char summaries (cheap triage). Use mode="full" when you actually need the article texts (slower, more tokens).
• health() - server status. Response: cascade / pool (warmFailures + fallback) / rateLimiter / cache / telemetry / selfHealing (current strategy order + stats) / config. Call it if searches start failing — pool.fallback=true or rising cascade.totalCaptchas are the usual culprits.

Env vars

Troubleshooting

• CAPTCHA in 4 modes (picked automatically from env):
  • default (local desktop): OS notification fires, headed Chrome opens, human solves, call retries
  • SURF_HEADLESS=false: headed Chrome opens, no notification (user is already watching)
  • SURF_REMOTE_DEBUG=true: DevTools port + instructions printed, attach chrome://inspect locally to solve
  • SURF_CLOUD_MODE=true: fail-fast with CAPTCHA_REQUIRED error
• Headed Chrome opens to a plain search box instead of CAPTCHA: just type any query in the box and press Enter. Subsequent calls work.
• "Chrome not found": install Chrome or set CHROME_PATH.
• Stale selectors: two-layer mitigation — runtime per-strategy reorder (SURF_SELF_HEALING, deterministic) + daily cron that opens draft PRs with candidate fixes (SURF_LLM_HEAL optional, human review required, never auto-merged).
• Searches feel slower than the Numbers table: check health().pool.fallback. true means the worker pool gave up after 3 warm failures and is using a single context. Usually fixed by npm run bootstrap to refresh the seed profile.
• SSRF: extract blocks localhost, private IPs, AWS metadata by default. Set SURF_ALLOW_PRIVATE=true to allow them.

Changelog

See CHANGELOG.md.

License

MIT