Google Surf MCP Server

by harimxchoiio.github.HarimxChoi/google-surf-mcpv1.1.3

Web, academic and code search with graph RAG, data lineage, ontology and cross-project schema links.

291Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active29d ago

Install Google Surf MCP server

claude mcp add google-surf -e SEARCH_API='<search-api>' -e GITHUB_TOKEN='<github-token>' -e ANTHROPIC_API_KEY='<anthropic-api-key>' -e ORCAROUTER_API_KEY='<orcarouter-api-key>' -- npx -y google-surf-mcp

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": [
        "-y",
        "google-surf-mcp"
      ],
      "env": {
        "SEARCH_API": "<search-api>",
        "GITHUB_TOKEN": "<github-token>",
        "ANTHROPIC_API_KEY": "<anthropic-api-key>",
        "ORCAROUTER_API_KEY": "<orcarouter-api-key>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": [
        "-y",
        "google-surf-mcp"
      ],
      "env": {
        "SEARCH_API": "<search-api>",
        "GITHUB_TOKEN": "<github-token>",
        "ANTHROPIC_API_KEY": "<anthropic-api-key>",
        "ORCAROUTER_API_KEY": "<orcarouter-api-key>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "google-surf": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "google-surf-mcp"
      ],
      "env": {
        "SEARCH_API": "<search-api>",
        "GITHUB_TOKEN": "<github-token>",
        "ANTHROPIC_API_KEY": "<anthropic-api-key>",
        "ORCAROUTER_API_KEY": "<orcarouter-api-key>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": [
        "-y",
        "google-surf-mcp"
      ],
      "env": {
        "SEARCH_API": "<search-api>",
        "GITHUB_TOKEN": "<github-token>",
        "ANTHROPIC_API_KEY": "<anthropic-api-key>",
        "ORCAROUTER_API_KEY": "<orcarouter-api-key>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
SEARCH_API	—	yes	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	—	yes	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	—	yes	Anthropic API key for optional LLM-assisted selector repair.
ORCAROUTER_API_KEY	—	yes	OrcaRouter API key for optional LLM-assisted selector repair.

Freshness

Active — last maintenance signal 29d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-09-10 · 29d ago · GitHub
Latest release
2026-09-10 · 29d ago · GitHub · v1.1.3
Package published
no data · npm/PyPI
Registry entry updated
2026-09-10 · 29d ago · official registry · v1.1.3

FAQ

›How do I install the Google Surf MCP server in Claude Code?

Run: claude mcp add google-surf -e SEARCH_API='<search-api>' -e GITHUB_TOKEN='<github-token>' -e ANTHROPIC_API_KEY='<anthropic-api-key>' -e ORCAROUTER_API_KEY='<orcarouter-api-key>' -- npx -y google-surf-mcp. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Google Surf require an API key?

Yes. It expects SEARCH_API, GITHUB_TOKEN, ANTHROPIC_API_KEY, ORCAROUTER_API_KEY, of which 4 are secrets.

›Can I use Google Surf as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is Google Surf in the official MCP registry?

Yes, as io.github.HarimxChoi/google-surf-mcp.