Google Surf Mcp

google-surf-mcp

English | Korean

Google Surf MCP searches the web, papers, and codebases, then uses Auto Ontology to organize what you read into a local knowledge graph. Start without an API key or a separate database server, and build a personal knowledge base from connected sources and project records.

[npm version] [npm downloads] [ci] [MCP Toplist] [google-surf-mcp MCP server]

[SearchApi Google Search API]

Sponsored by SearchApi

[Integrated project knowledge graph]

Core features

• Search and read: Find web pages, papers, PDFs, GitHub repositories, and indexed local code. Tree-sitter links files, code symbols, imports, and function calls.
• Auto Ontology: Organize sources and project records into a typed knowledge graph with evidence and data lineage.
• Cross-project search: Find stored sources across selected projects using exact-match, keyword, semantic, and graph retrieval, with RRF fusion and a shared reranker.
• Explore and export: Browse PKM, lineage, and ontology views; export HTML, PNG, JSON, Graphviz DOT, and Neo4j import bundles.

Stack: TypeScript, Chrome/Playwright, LiteParse, Tree-sitter, SurrealDB, Multilingual E5, and Graphology. Architecture

Quick start

Requires Node.js 22.12+ and Chrome or Chromium for browser search. CI covers Node 22 and 24 on Linux and Windows.

Register the server in your MCP client:

{  "mcpServers": {    "google-surf": {      "command": "npx",      "args": ["-y", "google-surf-mcp@latest"]    }  }}

Restart the client. Auto Ontology is enabled by default; the local embedding model may be downloaded when you first index content. For search and extraction without the database or embedding model, set SURF_RESEARCH=false in the server environment.

Client setup, local installation, and SearchApi configuration

Search

• Search through system Chrome without an API key
• Dedicated logged-out profile; your personal Chrome profile is never read or copied
• Multi-strategy SERP parsing with geometric verification
• Removal of sponsored results and knowledge panels
• CAPTCHA detection and environment-specific recovery
• Parser self-healing and context fallback

Browser search is the default. SearchApi is an optional primary provider or fallback; it requires your own account, key, and credits.

Supported AI providers and gateways

• OrcaRouter (free models available)

Optional LLM-assisted repair and OrcaRouter setup

Tools

Seven tools are available with Auto Ontology enabled:

Providing project_id to web search does not make it local-only. Use project_memory_search for stored knowledge.

Tool parameters, limits, follow-up reads, and repeatable source collection

Google Surf Auto Ontology

Search and extraction results are saved automatically. Plans, experiments, failures, and decisions are linked when your agent records them through project_memory.

Web + papers + code + project records                  |        Local knowledge graph                  |    Hybrid retrieval + source-backed evidence

Projects stay separate by default. Selected projects can link knowledge using matching DOIs, repository URLs, or explicitly registered aliases; original records are not merged or moved.

Create a standalone graph explorer for one project:

project_memory(action="export", project_id="my-project", export_format="html", export_view="graph")

The HTML explorer includes PKM, lineage, and ontology views with PNG/JSON downloads. DOT and Neo4j exports are also available. The feature was renamed from Research to Auto Ontology; existing SURF_RESEARCH* settings, project_memory* tools, CLI names, and storage paths still work.

Ontology, lineage, code indexing, and export details

Benchmark

Live web result ranking on 32 held-out queries:

Evaluation conditions, retrieval results, and resource measurements

Documentation

Contributing · Changelog · MIT License