PluginBench
MCP Server
Active
MIT

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.

RepositoryRegistry
How to choose

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.

transport: stdio
Config generated by PluginBench — verify against the source before use.
Environment / auth
  • SEARCH_API
    secret

    SearchApi API key. Required only for SearchApi primary or fallback modes.

  • SURF_SEARCH_PROVIDER

    Provider for search and search_parallel: browser, searchapi, or fallback. Defaults to browser.

  • SURF_SCHOLAR_PROVIDER

    Provider for scholar_search: browser, searchapi, or fallback. Defaults to browser.

  • SURF_BROWSER_ENGINE

    Browser engine: auto, native, or playwright. Auto uses one hidden native Chrome broker shared across local MCP sessions.

  • CHROME_PATH

    Absolute path to the Chrome binary. Auto-detected on Windows/macOS/Linux when omitted.

  • SURF_PROFILE_ROOT

    Directory for the warm Chrome profile. Defaults to ~/.google-surf-mcp.

  • SURF_RESEARCH

    Enable local project memory and hybrid retrieval. Defaults to true.

  • SURF_RETRIEVAL_MODE

    Shared route for search and search_parallel: live or hybrid. Defaults to hybrid.

  • SURF_RESEARCH_ROOT

    Embedded SurrealDB data directory. Defaults to <profile>/research.

  • SURF_RESEARCH_VECTOR_MODEL

    Local model for HNSW retrieval and shared reranking. Defaults to Xenova/multilingual-e5-small; use off to disable.

  • SURF_RESEARCH_VECTOR_LOW_MEMORY

    Disable ONNX CPU memory arena and memory pattern. Defaults to true.

  • SURF_RESEARCH_VECTOR_THREADS

    ONNX intra-op thread count from 1 to 16. Defaults to 4.

  • SURF_RESEARCH_REPO_AUTO

    Sparse-index at most one eligible small GitHub repository per search call. Defaults to true.

  • SURF_RESEARCH_REPO_AUTO_MAX_MB

    Maximum searchable repository source-text size in MB. Assets are excluded. Defaults to 20.

  • SURF_RESEARCH_REPO_AUTO_MAX_FILES

    Maximum repository source file count for automatic indexing. Defaults to 2000.

  • SURF_RESEARCH_BROKER_IDLE_MS

    Shared research broker idle lifetime in milliseconds. Defaults to 60000.

  • SURF_RESEARCH_READ_CONCURRENCY

    Maximum concurrent research broker reads. Defaults to 4.

  • SURF_RESEARCH_QUERY_TIMEOUT_MS

    Timeout per embedded SurrealDB query in milliseconds. Defaults to 120000; timed-out retrieval lanes are reported as partial.

  • GITHUB_TOKEN
    secret

    Optional token that raises GitHub API limits for repository inspection.

  • SURF_LOCALE

    Browser locale, e.g. en-US.

  • SURF_TZ

    IANA timezone, e.g. America/New_York. Defaults to system timezone.

  • SURF_HEADLESS

    Controls Playwright extraction, compatibility, and recovery paths. Native search hides normal system Chrome and shows it only for CAPTCHA recovery.

  • SURF_IDLE_CLOSE_MS

    Idle ms before closing the sequential ctx and pool. 0 disables idle auto-close. Defaults to 30000.

  • SURF_ALLOW_PRIVATE

    Set 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_HEAL

    Enable the optional workflow-only LLM selector repair path. Defaults to false.

  • SURF_LLM_PROVIDER

    LLM selector repair provider: anthropic or orcarouter. Defaults to anthropic.

  • SURF_LLM_MODEL

    Optional model override. OrcaRouter defaults to orcarouter/auto.

  • ANTHROPIC_API_KEY
    secret

    Anthropic API key for optional LLM-assisted selector repair.

  • ORCAROUTER_API_KEY
    secret

    OrcaRouter API key for optional LLM-assisted selector repair.

~/Library/Application Support/Claude/claude_desktop_config.json
JSON config
{
  "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

What is google-surf-mcp and why would I use it?

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.

Is it free to use?

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.

How do I install it in Claude or Cursor?

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.

Does it require authentication or API keys?

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.

What happens when Google shows a CAPTCHA?

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.

Can I extract full article text or just summaries?

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.

<img src="./assets/icon256.png" width="128" align="right" alt="google-surf-mcp"/>

google-surf-mcp

English | 한국어

npm version npm downloads ci google-surf-mcp MCP server

demo

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. 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_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)
  • ✅ 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-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+ 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 includes dropped count + dropped_reasons). Results cached 24h (SURF_CACHE_TTL_SEARCH_MS=0 to 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 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

vardefaultnotes
CHROME_PATHauto-detectedabsolute path to Chrome binary
SURF_PROFILE_ROOT~/.google-surf-mcpwhere the warm profile lives
SURF_LOCALEen-USbrowser locale
SURF_TZsystem tze.g. America/New_York
SURF_HEADLESStrueset false to run Chrome visibly (demos / debugging). When false, CAPTCHA recovery skips the OS notification (user is already watching).
SURF_REMOTE_DEBUGfalseset 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_MS30000idle 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_PRIVATEfalseset 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_CHARS8000default extract truncation (200–50000); per-call max_chars still overrides
SURF_EXTRACT_OCRfalseOCR scanned/image PDFs via Tesseract (slower; off by default)
SURF_CLOUD_MODEfalseheadless/serverless mode: TLS bypass + --no-sandbox + --disable-dev-shm-usage + worker pool disabled + fail-fast on CAPTCHA
SURF_CASCADE_DISABLEDfalsepin a single stealth mode (chosen by SURF_USE_STEALTH) instead of the 3-tier auto-cascade
SURF_USE_STEALTHtrueinitial stealth tier — only consulted when SURF_CASCADE_DISABLED=true
SURF_HUMANLIKE_MODEoffoff / background (fire-and-forget after returning results) / inline (await before returning, slower) — opt-in humanlike browsing
SURF_RATE_LIMIT_PER_MIN10internal cap on Google-facing requests per minute
SURF_CACHE_TTL_SEARCH_MS86400000search cache TTL (24h); 0 disables caching
SURF_CACHE_MAX_ENTRIES1000LRU cap per cache namespace
SURF_CACHE_ROOT<profile>/cachecache 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_TELEMETRYfalseset 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>/telemetrydirectory for jsonl telemetry files. UTC-dated one file per day (YYYY-MM-DD.jsonl).
SURF_SELF_HEALINGtrueper-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.jsonpersistence path for healing state. Atomic tmp+rename writes; debounced 5s.
SURF_LLM_HEALfalseopt-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, 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

Related MCP servers

Canadian procurement intelligence: CanadaBuys and Alberta tenders, ranked for your shop.

0
Python
View repository →

Search volunteer opportunities across Spain via hacesfalta.org

0
TypeScript
View repository →

Verified Polish open data for AI agents: debt, budget, 460 MPs, votings, judiciary search, RAG.

1
TypeScript
MIT
View repository →

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.

4
TypeScript
MIT
View repository →