google-surf-mcp

Package (npm 1.1.3)

npx -y [email protected]

Or add to your MCP client config:

{
  "mcpServers": {
    "google-surf-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "SEARCH_API": "<YOUR_VALUE>",
        "SURF_SEARCH_PROVIDER": "<YOUR_VALUE>",
        "SURF_SCHOLAR_PROVIDER": "<YOUR_VALUE>",
        "SURF_BROWSER_ENGINE": "<YOUR_VALUE>",
        "CHROME_PATH": "<YOUR_VALUE>",
        "SURF_PROFILE_ROOT": "<YOUR_VALUE>",
        "SURF_RESEARCH": "<YOUR_VALUE>",
        "SURF_RETRIEVAL_MODE": "<YOUR_VALUE>",
        "SURF_RESEARCH_ROOT": "<YOUR_VALUE>",
        "SURF_RESEARCH_VECTOR_MODEL": "<YOUR_VALUE>",
        "SURF_RESEARCH_VECTOR_LOW_MEMORY": "<YOUR_VALUE>",
        "SURF_RESEARCH_VECTOR_THREADS": "<YOUR_VALUE>",
        "SURF_RESEARCH_REPO_AUTO": "<YOUR_VALUE>",
        "SURF_RESEARCH_REPO_AUTO_MAX_MB": "<YOUR_VALUE>",
        "SURF_RESEARCH_REPO_AUTO_MAX_FILES": "<YOUR_VALUE>",
        "SURF_RESEARCH_BROKER_IDLE_MS": "<YOUR_VALUE>",
        "SURF_RESEARCH_READ_CONCURRENCY": "<YOUR_VALUE>",
        "SURF_RESEARCH_QUERY_TIMEOUT_MS": "<YOUR_VALUE>",
        "GITHUB_TOKEN": "<YOUR_VALUE>",
        "SURF_LOCALE": "<YOUR_VALUE>",
        "SURF_TZ": "<YOUR_VALUE>",
        "SURF_HEADLESS": "<YOUR_VALUE>",
        "SURF_IDLE_CLOSE_MS": "<YOUR_VALUE>",
        "SURF_ALLOW_PRIVATE": "<YOUR_VALUE>",
        "SURF_LLM_HEAL": "<YOUR_VALUE>",
        "SURF_LLM_PROVIDER": "<YOUR_VALUE>",
        "SURF_LLM_MODEL": "<YOUR_VALUE>",
        "ANTHROPIC_API_KEY": "<YOUR_VALUE>",
        "ORCAROUTER_API_KEY": "<YOUR_VALUE>"
      }
    }
  }
}

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