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
+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-07Google 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