HarimxChoi /google-surf-mcp

Turn Google Search, Papers, and Codebases into an Automatic Local Knowledge Graph for AI Agents.

★ 301⑂ 32👁 1⑃ 10● 4▤ 37
TypeScriptMITCreated 2026-04-30
Download: Google Surf MCP v1.1.6Google-1.1.6 ↓1.1.62026-11-07
+1
Daily
301
stars
32
forks
1
watchers
10
prs
4
issues
37
releases

README

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.








  

Sponsored by SearchApi



 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:

json
{
  "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:

| Tool | Use |
| --- | --- |
| search / search_parallel | Discover new web sources and read them in the same call with extract_mode. |
| scholar_search | Find paper-specific Google Scholar metadata. |
| extract | Read a web page, PDF, or repository from an already-known URL. |
| project_memory_search | Local-only search of indexed project knowledge; no live web search. |
| project_memory | Manage projects, save research records, index user-approved local folders, and export graphs. |
| health | Inspect search and local runtime status. |

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

Top issues

Latest release

Google Surf MCP v1.1.6 v1.1.6 2026-11-07
Google Surf MCP 1.1.6 improves Auto Ontology, evidence handling, and optional provider setup.

- Adds query-focused evidence, cached follow-up reads, and explicit requirement/gap receipts. The balanced default is preserved; coherent extraction is opt-in.
- Separates ontology schema terms from instance assertions and adds project-, time-, and unit-aware full-population aggregates.
- Fixes pinned E5 tokenizer discovery and fingerprints embedding/runtime compatibility.
- Isolates source-reading browser traffic with DNS-validated, IP-pinned requests and private-network guards.
- Integrates optiona

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON