google-surf-mcp

How to start

1. Run the command in your terminal, in the project where you want it.
2. Sign in if asked the first time Claude connects.
3. Check it: run /mcp in Claude Code and look for it in the list.

What it needs

• SEARCH_APIOptional. Secret: keep it out of your repo. SearchApi API key. Required only for SearchApi primary or fallback modes.
• SURF_SEARCH_PROVIDEROptional. Provider for search and search_parallel: browser, searchapi, or fallback. Defaults to browser.
• SURF_SCHOLAR_PROVIDEROptional. Provider for scholar_search: browser, searchapi, or fallback. Defaults to browser.
• SURF_BROWSER_ENGINEOptional. Browser engine: auto, native, or playwright. Auto uses one hidden native Chrome broker shared across local MCP sessions.
• CHROME_PATHOptional. Absolute path to the Chrome binary. Auto-detected on Windows/macOS/Linux when omitted.
• SURF_PROFILE_ROOTOptional. Directory for the warm Chrome profile. Defaults to ~/.google-surf-mcp.
• SURF_RESEARCHOptional. Enable local project memory and hybrid retrieval. Defaults to true.
• SURF_RETRIEVAL_MODEOptional. Shared route for search and search_parallel: live or hybrid. Defaults to hybrid.
• SURF_RESEARCH_ROOTOptional. Embedded SurrealDB data directory. Defaults to <profile>/research.
• SURF_RESEARCH_VECTOR_MODELOptional. Local model for HNSW retrieval and shared reranking. Defaults to Xenova/multilingual-e5-small; use off to disable.
• SURF_RESEARCH_VECTOR_LOW_MEMORYOptional. Disable ONNX CPU memory arena and memory pattern. Defaults to true.
• SURF_RESEARCH_VECTOR_THREADSOptional. ONNX intra-op thread count from 1 to 16. Defaults to 4.
• SURF_RESEARCH_REPO_AUTOOptional. Sparse-index at most one eligible small GitHub repository per search call. Defaults to true.
• SURF_RESEARCH_REPO_AUTO_MAX_MBOptional. Maximum searchable repository source-text size in MB. Assets are excluded. Defaults to 20.
• SURF_RESEARCH_REPO_AUTO_MAX_FILESOptional. Maximum repository source file count for automatic indexing. Defaults to 2000.
• SURF_RESEARCH_BROKER_IDLE_MSOptional. Shared research broker idle lifetime in milliseconds. Defaults to 60000.
• SURF_RESEARCH_READ_CONCURRENCYOptional. Maximum concurrent research broker reads. Defaults to 4.
• SURF_RESEARCH_QUERY_TIMEOUT_MSOptional. Timeout per embedded SurrealDB query in milliseconds. Defaults to 120000; timed-out retrieval lanes are reported as partial.
• GITHUB_TOKENOptional. Secret: keep it out of your repo. Optional token that raises GitHub API limits for repository inspection.
• SURF_LOCALEOptional. Browser locale, e.g. en-US.
• SURF_TZOptional. IANA timezone, e.g. America/New_York. Defaults to system timezone.
• SURF_HEADLESSOptional. Controls Playwright extraction, compatibility, and recovery paths. Native search hides normal system Chrome and shows it only for CAPTCHA recovery.
• SURF_IDLE_CLOSE_MSOptional. Idle ms before closing the sequential ctx and pool. 0 disables idle auto-close. Defaults to 30000.
• SURF_ALLOW_PRIVATEOptional. 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_HEALOptional. Enable the optional workflow-only LLM selector repair path. Defaults to false.
• SURF_LLM_PROVIDEROptional. LLM selector repair provider: anthropic or orcarouter. Defaults to anthropic.
• SURF_LLM_MODELOptional. Optional model override. OrcaRouter defaults to orcarouter/auto.
• ANTHROPIC_API_KEYOptional. Secret: keep it out of your repo. Anthropic API key for optional LLM-assisted selector repair.
• ORCAROUTER_API_KEYOptional. Secret: keep it out of your repo. OrcaRouter API key for optional LLM-assisted selector repair.

Environment variables as listed in the server's MCP Registry entry.