io.github.HarimxChoi/google-surf-mcp MCP Server
io.github.HarimxChoi/google-surf-mcp
Web, academic, and code search with graph RAG and data lineage—no API key required.
What this kind of tool is for
- Let your agent search the web or a document set and cite what it found.
- Pull structured facts out of pages instead of copy-pasting by hand.
- Track changes on a topic over days without re-reading everything.
How to compare servers like this
- Source coverage:
- Check which engines, sites, or document types the tool can actually reach.
- Citation behavior:
- Prefer tools that return links you can open, not just summarized claims.
- Terms of service:
- Some sources forbid automated access; make sure the tool stays inside them.
- Maintenance signal:
- Scrapers break silently when pages change; recent commits are the best proxy.
This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.
What is the io.github.HarimxChoi/google-surf-mcp MCP server?
The google-surf-mcp MCP server provides Google search, URL extraction, and academic PDF parsing in a single tool suite. It requires no API key, handles CAPTCHAs via human intervention, and combines search results with inline content extraction for web pages and academic papers from arxiv, bioRxiv, Nature, OpenReview, and other sources.
google-surf-mcp replaces three separate MCPs (search + URL fetcher + academic-paper extractor) with one unified server. It performs Google searches at ~1.5s per query, extracts article and PDF content with configurable detail levels (abstract, full, or metadata), and runs searches in parallel for efficiency. Built on Playwright with a persistent Chrome profile, it handles CAPTCHAs through OS notifications or headless modes, and includes self-healing parser strategies to adapt to Google's changing page structure.
How to install io.github.HarimxChoi/google-surf-mcp
Copy-paste configuration for popular MCP clients.
SEARCH_APIsecretSearchApi API key. Required only for SearchApi primary or fallback modes.
SURF_SEARCH_PROVIDERProvider for search and search_parallel: browser, searchapi, or fallback. Defaults to browser.
SURF_SCHOLAR_PROVIDERProvider for scholar_search: browser, searchapi, or fallback. Defaults to browser.
SURF_BROWSER_ENGINEBrowser engine: auto, native, or playwright. Auto uses one hidden native Chrome broker shared across local MCP sessions.
CHROME_PATHAbsolute path to the Chrome binary. Auto-detected on Windows/macOS/Linux when omitted.
SURF_PROFILE_ROOTDirectory for the warm Chrome profile. Defaults to ~/.google-surf-mcp.
SURF_RESEARCHEnable local project memory and hybrid retrieval. Defaults to true.
SURF_RETRIEVAL_MODEShared route for search and search_parallel: live or hybrid. Defaults to hybrid.
SURF_RESEARCH_ROOTEmbedded SurrealDB data directory. Defaults to <profile>/research.
SURF_RESEARCH_VECTOR_MODELLocal model for HNSW retrieval and shared reranking. Defaults to Xenova/multilingual-e5-small; use off to disable.
SURF_RESEARCH_VECTOR_LOW_MEMORYDisable ONNX CPU memory arena and memory pattern. Defaults to true.
SURF_RESEARCH_VECTOR_THREADSONNX intra-op thread count from 1 to 16. Defaults to 4.
SURF_RESEARCH_REPO_AUTOSparse-index at most one eligible small GitHub repository per search call. Defaults to true.
SURF_RESEARCH_REPO_AUTO_MAX_MBMaximum searchable repository source-text size in MB. Assets are excluded. Defaults to 20.
SURF_RESEARCH_REPO_AUTO_MAX_FILESMaximum repository source file count for automatic indexing. Defaults to 2000.
SURF_RESEARCH_BROKER_IDLE_MSShared research broker idle lifetime in milliseconds. Defaults to 60000.
SURF_RESEARCH_READ_CONCURRENCYMaximum concurrent research broker reads. Defaults to 4.
SURF_RESEARCH_QUERY_TIMEOUT_MSTimeout per embedded SurrealDB query in milliseconds. Defaults to 120000; timed-out retrieval lanes are reported as partial.
GITHUB_TOKENsecretOptional token that raises GitHub API limits for repository inspection.
SURF_LOCALEBrowser locale, e.g. en-US.
SURF_TZIANA timezone, e.g. America/New_York. Defaults to system timezone.
SURF_HEADLESSControls Playwright extraction, compatibility, and recovery paths. Native search hides normal system Chrome and shows it only for CAPTCHA recovery.
SURF_IDLE_CLOSE_MSIdle ms before closing the sequential ctx and pool. 0 disables idle auto-close. Defaults to 30000.
SURF_ALLOW_PRIVATESet to 'true' to allow extract on private/loopback addresses (localhost, 10.x, 192.168.x, 169.254.x, etc). Default blocks them as an SSRF guard.
SURF_LLM_HEALEnable the optional workflow-only LLM selector repair path. Defaults to false.
SURF_LLM_PROVIDERLLM selector repair provider: anthropic or orcarouter. Defaults to anthropic.
SURF_LLM_MODELOptional model override. OrcaRouter defaults to orcarouter/auto.
ANTHROPIC_API_KEYsecretAnthropic API key for optional LLM-assisted selector repair.
ORCAROUTER_API_KEYsecretOrcaRouter API key for optional LLM-assisted selector repair.
{
"mcpServers": {
"google-surf-mcp": {
"command": "npx",
"args": [
"-y",
"google-surf-mcp"
],
"env": {
"SEARCH_API": "<YOUR_SEARCH_API>",
"SURF_SEARCH_PROVIDER": "<YOUR_SURF_SEARCH_PROVIDER>",
"SURF_SCHOLAR_PROVIDER": "<YOUR_SURF_SCHOLAR_PROVIDER>",
"SURF_BROWSER_ENGINE": "<YOUR_SURF_BROWSER_ENGINE>",
"CHROME_PATH": "<YOUR_CHROME_PATH>",
"SURF_PROFILE_ROOT": "<YOUR_SURF_PROFILE_ROOT>",
"SURF_RESEARCH": "<YOUR_SURF_RESEARCH>",
"SURF_RETRIEVAL_MODE": "<YOUR_SURF_RETRIEVAL_MODE>",
"SURF_RESEARCH_ROOT": "<YOUR_SURF_RESEARCH_ROOT>",
"SURF_RESEARCH_VECTOR_MODEL": "<YOUR_SURF_RESEARCH_VECTOR_MODEL>",
"SURF_RESEARCH_VECTOR_LOW_MEMORY": "<YOUR_SURF_RESEARCH_VECTOR_LOW_MEMORY>",
"SURF_RESEARCH_VECTOR_THREADS": "<YOUR_SURF_RESEARCH_VECTOR_THREADS>",
"SURF_RESEARCH_REPO_AUTO": "<YOUR_SURF_RESEARCH_REPO_AUTO>",
"SURF_RESEARCH_REPO_AUTO_MAX_MB": "<YOUR_SURF_RESEARCH_REPO_AUTO_MAX_MB>",
"SURF_RESEARCH_REPO_AUTO_MAX_FILES": "<YOUR_SURF_RESEARCH_REPO_AUTO_MAX_FILES>",
"SURF_RESEARCH_BROKER_IDLE_MS": "<YOUR_SURF_RESEARCH_BROKER_IDLE_MS>",
"SURF_RESEARCH_READ_CONCURRENCY": "<YOUR_SURF_RESEARCH_READ_CONCURRENCY>",
"SURF_RESEARCH_QUERY_TIMEOUT_MS": "<YOUR_SURF_RESEARCH_QUERY_TIMEOUT_MS>",
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
"SURF_LOCALE": "<YOUR_SURF_LOCALE>",
"SURF_TZ": "<YOUR_SURF_TZ>",
"SURF_HEADLESS": "<YOUR_SURF_HEADLESS>",
"SURF_IDLE_CLOSE_MS": "<YOUR_SURF_IDLE_CLOSE_MS>",
"SURF_ALLOW_PRIVATE": "<YOUR_SURF_ALLOW_PRIVATE>",
"SURF_LLM_HEAL": "<YOUR_SURF_LLM_HEAL>",
"SURF_LLM_PROVIDER": "<YOUR_SURF_LLM_PROVIDER>",
"SURF_LLM_MODEL": "<YOUR_SURF_LLM_MODEL>",
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"ORCAROUTER_API_KEY": "<YOUR_ORCAROUTER_API_KEY>"
}
}
}
}Tools & capabilities
Tools this server exposes to the agent.
search— Single Google search query returning title, URL, and snippet. Drops sponsored ads and knowledge panels. Results cached 24h by default.search_parallel— Parallel pool of 4 workers for up to 10 queries per call, ~1.5s wall time.extract— Fetch and parse a URL. Supports mode="full" (whole body), mode="abstract" (~1500 chars), or mode="metadata" (PDF page count only). Handles HTML via Readability and PDFs via spatial parsing.search_extract— Combined search + parallel extract in one call. Default mode="abstract" returns SERP results enriched with ~1500-char summaries; mode="full" includes complete article text.health— Server status including cascade tier, worker pool state, rate limiter, cache, telemetry, and self-healing strategy order.
Use cases
- Research academic papers across arxiv, bioRxiv, Nature, and other repositories with inline PDF extraction
- Quickly triage search results with abstract-mode summaries before fetching full article text
- Perform parallel multi-query searches to gather competitive intelligence or market research in seconds
- Extract and parse web articles and PDFs for content analysis without manual copy-paste
- Monitor search reliability and diagnose CAPTCHA or pool failures via health checks
io.github.HarimxChoi/google-surf-mcp MCP server FAQ
It's a Google search MCP that combines web search, URL fetching, and academic PDF extraction in one tool. Unlike other search MCPs, it actually works, requires no API key, and handles CAPTCHAs automatically via human intervention or headless modes.
Yes. It uses Google's public search interface with no API key, no paid proxies, and no CAPTCHA solver fees. You only need Chrome/Chromium installed locally.
Run `npx google-surf-mcp` and add the JSON config to your MCP client (e.g., `~/.claude.json`). For Claude Code: paste the config block with command `npx` and args `["-y", "google-surf-mcp"]`, then restart. For other clients, use the same JSON shape in their config file.
No. It uses a persistent local Chrome profile that auto-bootstraps on first call. No API keys, proxies, or solver services needed. For `SURF_LLM_HEAL=true` (optional self-healing), you can provide your own `ANTHROPIC_API_KEY`, but the default deterministic healing never makes external requests.
The server handles it in 4 modes: (1) default—OS notification + headed Chrome opens for human solve; (2) `SURF_HEADLESS=false`—headed Chrome only; (3) `SURF_REMOTE_DEBUG=true`—DevTools port printed for remote solve; (4) `SURF_CLOUD_MODE=true`—fail-fast error. Each solve preserves the profile's reputation with Google.
Both. `search_extract` defaults to `mode="abstract"` (~1500 chars, token-cheap) for quick triage. Set `mode="full"` to get complete article bodies. The `extract` tool also supports both modes independently.
README (reference)
Source of truth, from the repository.
google-surf-mcp
English | 한국어

Demo only. Actual searches run headless by default (no visible browser). Set
SURF_HEADLESS=falseto make Chrome visible like in the clip above.
Google search MCP. No API key. Just works.
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_extractdefaults 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) - ✅ No API key, no proxies, no solver
5 tools: 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
| result | |
|---|---|
| sequential | ~1.5s/query (first call ~4s, includes setup) |
| parallel x4 | ~1.5s wall (first call ~9s, includes pool warm) |
| parallel x10 | ~4.5s wall |
| search_extract x5 (abstract, default) | ~3s wall |
| search_extract x5 (full) | ~5s wall (search + 5 parallel extracts) |
Measured on a workstation with a 1Gb/s connection.
Stack
- Playwright + persistent Chrome profile
playwright-extrastealth as a cascade fallback tier- Multi-strategy SERP parser + geometric verification (drops sponsored / knowledge_panel / related)
@llamaindex/liteparsefor 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+ and Google Chrome (or Chromium) on the system.
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, search_parallel, extract, search_extract, health are now available.
For other MCP clients, use the same JSON shape in their config file.
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. Returns title / url / snippet. Sponsored ads + knowledge-panel dropped (response includesdroppedcount +dropped_reasons). Results cached 24h (SURF_CACHE_TTL_SEARCH_MS=0to bypass).search_parallel(queries[], limit?)- pool of 4, max 10 queries per call.extract(url, max_chars?, mode?)- fetch a URL, return article content.mode="full"(default): whole body. HTML via Readability, PDFs vialiteparse(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. Defaultmode="abstract"returns SERP enriched with ~1500-char summaries (cheap triage). Usemode="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=trueor risingcascade.totalCaptchasare the usual culprits.
Env vars
| var | default | notes |
|---|---|---|
CHROME_PATH | auto-detected | absolute path to Chrome binary |
SURF_PROFILE_ROOT | ~/.google-surf-mcp | where the warm profile lives |
SURF_LOCALE | en-US | browser locale |
SURF_TZ | system tz | e.g. America/New_York |
SURF_HEADLESS | true | set false to run Chrome visibly (demos / debugging). When false, CAPTCHA recovery skips the OS notification (user is already watching). |
SURF_REMOTE_DEBUG | false | set true on a headless server with remote DevTools. CAPTCHA path emits the DevTools port and throws instead of spawning a window; attach chrome://inspect from a local machine over SSH port-forward to solve. |
SURF_IDLE_CLOSE_MS | 30000 | idle ms before closing the sequential ctx and pool. 0 disables idle auto-close. Lower = faster cleanup, higher = warmer cache for spaced-out calls. |
SURF_ALLOW_PRIVATE | false | set true to allow extract to fetch private/loopback addresses (localhost, 127.0.0.1, 10.x, 192.168.x, 169.254.x, etc). Default blocks them as an SSRF guard. |
SURF_EXTRACT_MAX_CHARS | 8000 | default extract truncation (200–50000); per-call max_chars still overrides |
SURF_EXTRACT_OCR | false | OCR scanned/image PDFs via Tesseract (slower; off by default) |
SURF_CLOUD_MODE | false | headless/serverless mode: TLS bypass + --no-sandbox + --disable-dev-shm-usage + worker pool disabled + fail-fast on CAPTCHA |
SURF_CASCADE_DISABLED | false | pin a single stealth mode (chosen by SURF_USE_STEALTH) instead of the 3-tier auto-cascade |
SURF_USE_STEALTH | true | initial stealth tier — only consulted when SURF_CASCADE_DISABLED=true |
SURF_HUMANLIKE_MODE | off | off / background (fire-and-forget after returning results) / inline (await before returning, slower) — opt-in humanlike browsing |
SURF_RATE_LIMIT_PER_MIN | 10 | internal cap on Google-facing requests per minute |
SURF_CACHE_TTL_SEARCH_MS | 86400000 | search cache TTL (24h); 0 disables caching |
SURF_CACHE_MAX_ENTRIES | 1000 | LRU cap per cache namespace |
SURF_CACHE_ROOT | <profile>/cache | cache directory |
SURF_INSECURE_TLS | =SURF_CLOUD_MODE | --ignore-certificate-errors (auto-on in cloud mode) |
SURF_NO_SANDBOX | =SURF_CLOUD_MODE | --no-sandbox (auto-on in cloud mode) |
SURF_TELEMETRY | false | set true to enable jsonl event logging (search outcomes, cache hits/misses, tool errors, parser staleness) under {SURF_TELEMETRY_ROOT}. Designed as the input feed for the self-healing pipeline. Off by default. |
SURF_TELEMETRY_ROOT | <profile>/telemetry | directory for jsonl telemetry files. UTC-dated one file per day (YYYY-MM-DD.jsonl). |
SURF_SELF_HEALING | true | per-strategy outcome tracking + persisted reordering. Healing must win by 3 outcomes before reorder kicks in, so single-call flapping is impossible. Set false to pin the default strategy order. |
SURF_SELF_HEALING_FILE | <profile>/.heal/strategy-order.json | persistence path for healing state. Atomic tmp+rename writes; debounced 5s. |
SURF_LLM_HEAL | false | opt-in for LLM-assisted selector repair in the workflow-only repairWithLLM helper. Off by default → no third-party LLM request ever fires. When true, requires ANTHROPIC_API_KEY (your own); the package never ships a maintainer key. |
ANTHROPIC_API_KEY | — | your Anthropic key. Read only when SURF_LLM_HEAL=true. The runtime self-healing in SURF_SELF_HEALING is deterministic and never reads this variable. |
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, attachchrome://inspectlocally to solveSURF_CLOUD_MODE=true: fail-fast withCAPTCHA_REQUIREDerror
- 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_HEALoptional, human review required, never auto-merged). - Searches feel slower than the Numbers table: check
health().pool.fallback.truemeans the worker pool gave up after 3 warm failures and is using a single context. Usually fixed bynpm run bootstrapto refresh the seed profile. - SSRF:
extractblockslocalhost, private IPs, AWS metadata by default. SetSURF_ALLOW_PRIVATE=trueto allow them.
Changelog
See CHANGELOG.md.
License
MIT
Related MCP servers
Canadian procurement intelligence: CanadaBuys and Alberta tenders, ranked for your shop.
Verified Polish open data for AI agents: debt, budget, 460 MPs, votings, judiciary search, RAG.
Sourced property-tax protest facts; homeowner reviews and files. Not a law firm; no outcome claims.
Ask Telegraph's ranked miners from any MCP client, no wallet. Morse pays; each answer has a receipt.
View repository →Computer-use MCP for Windows 10/11: 32 tools — screenshot, UIA, Chrome CDP, type/click/scroll, VBA.




