Skip to content
Back to search

google-surf-mcp

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/HarimxChoi/google-surf-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/HarimxChoi/google-surf-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/harimxchoi--google-surf-mcp/badge.svg)](/listings/harimxchoi--google-surf-mcp)

HTML

<a href="/listings/harimxchoi--google-surf-mcp"><img src="/api/listings/harimxchoi--google-surf-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node 20.18.1+. Browser mode also requires Google Chrome or Chromium.

npx google-surf-mcp   # actual MCP - register in client config

First tool call auto-bootstraps the warm profile (you may see Chrome open briefly).

Or local clone:

git clone https://github.com/HarimxChoi/google-surf-mcp
cd google-surf-mcp
npm install

If auto-bootstrap fails (rare), run it manually:

npm run bootstrap

Override paths if needed:

CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap

Optional Codex output protection

Google Surf can install an opt-in [Codex hook](https://developers.openai.com/codex/hooks) that ranks oversized Bash output before it reaches the model. The host still executes the command; the hook only applies stateless source-order, exact, and BM25 ranking with RRF. It opens neither the Google Surf database nor a browser and does not store command output.

npx -y google-surf-mcp@latest hooks install --host codex

Restart Codex, then open `/hooks` to review and trust the definitions. Shell output is reranked from 1,500 characters, with a default 1,500-character display budget that expands up to 3,000 for distinct query-matching evidence records or blocks. An explicit override may exceed 3,000; there is no cumulative per-turn output limit. Two identical or near-duplicate searches and explicit foreground polling loops are blocked. Existing `write_stdin` polls for an already-running unified command remain controlled by the Codex runtime, not this hook.

JSON/JSONL summaries use compact records with input-relative JSON pointers, ancestor identity/condition references and original result values. Markdown table rows retain headers and adjacent context, including source lines. Selected records and their required context must fit together; the renderer reports omissions instead of slicing records. Plain logs retain block reranking. Selection is deterministic and lexical, without a model, database or extra subprocess. Context extraction uses structural/field-name heuristics, not semantic understanding; unselected fields remain in the original input. These excerpts do not replace experiment logs or SSOT history. Input-relative pointers are not persistent retrieval handles. Existing installed hook bundles require an update to use changed code.

npx -y google-surf-mcp@latest hooks status --host codex
npx -y google-surf-mcp@latest hooks update --host codex
npx -y google-surf-mcp@latest hooks uninstall --host codex

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 153 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <img src="./assets/icon256.png" width="128" align="right" alt="google-surf-mcp"/>
  2. # google-surf-mcp
  3. English | [Korean](./README.ko.md)
  4. [![npm version](https://img.shields.io/npm/v/google-surf-mcp)](https://www.npmjs.com/package/google-surf-mcp)
  5. [![npm downloads](https://img.shields.io/npm/dm/google-surf-mcp)](https://www.npmjs.com/package/google-surf-mcp)
  6. [![ci](https://github.com/HarimxChoi/google-surf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/HarimxChoi/google-surf-mcp/actions/workflows/ci.yml)
  7. [![MCP Toplist](https://mcptoplist.com/badge/io.github.HarimxChoi%2Fgoogle-surf-mcp.svg)](https://mcptoplist.com/server/io.github.HarimxChoi%2Fgoogle-surf-mcp)
  8. [![google-surf-mcp MCP server](https://glama.ai/mcp/servers/HarimxChoi/google-surf-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HarimxChoi/google-surf-mcp)
  9. <p align="center">
  10. <a href="https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp"><img src="./assets/searchapi-banner.png" width="100%" alt="SearchApi Google Search API" /></a>
  11. </p>
  12. <p align="center">Sponsored by <a href="https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp">SearchApi</a></p>
  13. [Install](#quick-start) · [Benchmarks](#benchmarks) · [Architecture](#architecture) · [Tools](#tools)
  14. Google Surf MCP searches the web, papers, and codebases, then uses Auto Ontology to organize what you read into a local knowledge graph.
  15. Start without an API key or a separate database server, and build a personal knowledge base from connected sources and project records.
  16. ## Benchmarks
  17. ### Web search vs Google AI Mode
  18. Eight developer questions covered Python TaskGroup, SQLite WAL, Kubernetes probes, Fetch, Redis TTL, Docker Compose, PyTorch, and Rust. Examples included SQLite's concurrent-writer limitations and whether PyTorch's `inference_mode()` replaces `model.eval()`.
  19. The answer model paired with Google Surf was **[DeepSeek V4.1 Flash (1017)](https://api-docs.deepseek.com/updates/)** (`deepseek-flash`, temperature 0, thinking disabled).
  20. | Evaluation | Google Surf + DeepSeek | Google AI Mode |
  21. | --- | ---: | ---: |
  22. | Result | **22/24** | **24/24** |
  23. Three required checkpoints per question; the numbers count fully met checkpoints, not whole-answer accuracy. Recorded on 2026-11-07, not a new evaluation of the current release.
  24. ### Auto Ontology comparison
  25. <a href="./assets/auto-ontology-benchmark.png"><img src="./assets/auto-ontology-benchmark.png" width="720" alt="Auto Ontology benchmark: NVIDIA 113/120, Google Surf 116/120, using the same 120 questions and DeepSeek model." /></a>
  26. Both systems built ontologies from 48 revision-pinned model-card and configuration files covering 16 open-weight model releases. Their retrieved evidence was passed to the same DeepSeek V4.1 Flash (1017) model (`deepseek-flash`), SQL-generation prompt, and database: **Google Surf 116/120, NVIDIA Auto Ontology 113/120**. This compares ontology-backed retrieval, not the products' default agents.
  27. [Evaluation setup, live-ranking results, and resource measurements](./guides/benchmarks.md)
  28. ## Architecture
  29. <a href="./assets/architecture-en.png"><img src="./assets/architecture-en.png" width="100%" alt="Google Surf architecture: live discovery, source reading, and local project retrieval converge on bounded source-backed evidence." /></a>
  30. ### Technology stack
  31. | Layer | Technologies |
  32. | --- | --- |
  33. | Runtime and protocol | TypeScript, Node.js 22.13+, MCP SDK, Zod |
  34. | Browser search | System Chrome, Playwright, shared browser broker and reusable tabs |
  35. | Source reading | HTTP, isolated headless BrowserContext, Mozilla Readability, Turndown |
  36. | Documents and OCR | LiteParse CPU OCR; optional Xberg for Office; OfficeParser fallback; hwp-convert; pdf-lib; Sharp |
  37. | Local storage | SurrealDB with embedded RocksDB, durable catalog and payloads, rebuildable indexes |
  38. | Retrieval and ranking | Exact match, BM25, Multilingual E5-small q8/ONNX, HNSW, graph retrieval, RRF, cached E5 reranking |
  39. | Code indexing | Tree-sitter for Python, TypeScript, and C++ structure |
  40. | Graph analysis | Graphology, PageRank, Louvain communities, provenance and lineage projections |
  41. | Network controls | Undici, DNS/IP-pinned reads, SSRF checks, deny-by-default source-reader proxy |
  42. OCR is configurable; Xberg does not add another OCR or embedding model. Live-only search uses BM25/RRF without loading E5. [Architecture details](./guides/auto-ontology.md) · [Lightweight configuration](./examples/lightweight-documents.env)
  43. ## Quick start
  44. Requires Node.js 22.13+ and Chrome or Chromium for browser search. CI covers Node 22 and 24 on Linux and Windows.
  45. Register the server in your MCP client:
  46. ```json
  47. {
  48. "mcpServers": {
  49. "google-surf": {
  50. "command": "npx",
  51. "args": ["-y", "google-surf-mcp@latest"]
  52. }
  53. }
  54. }
  55. ```
  56. Restart the client. Auto Ontology is enabled by default; the local embedding model may be downloaded when you first index content.
  57. For search and extraction without the database or embedding model, set `SURF_RESEARCH=false` in the server environment.
  58. [Client setup, local installation, and SearchApi configuration](./guides/getting-started.md)
  59. ## Search
  60. - Search through system Chrome without an API key
  61. - Dedicated logged-out profile; your personal Chrome profile is never read or copied
  62. - Multi-strategy SERP parsing with geometric verification
  63. - Removal of sponsored results and knowledge panels
  64. - CAPTCHA detection and environment-specific recovery
  65. - Parser self-healing and context fallback
  66. Browser search is the default. [SearchApi](https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp) is an optional primary provider or fallback; it requires your own account, key, and credits.
  67. ## Supported AI providers and gateways
  68. - [OrcaRouter](https://www.orcarouter.ai/ref/ref_7fd137d6c7b30793af2f) (free models available)
  69. [Optional LLM-assisted repair and OrcaRouter setup](./guides/configuration.md#orcarouter)
  70. ## Tools
  71. Seven tools are available with Auto Ontology enabled:
  72. | Tool | Use |
  73. | --- | --- |
  74. | `search` / `search_parallel` | Discover **new web sources** and read them in the same call with `extract_mode`. |
  75. | `scholar_search` | Find paper-specific Google Scholar metadata. |
  76. | `extract` | Read a web page, PDF, or repository from an **already-known URL**. |
  77. | `project_memory_search` | **Local-only** search of indexed project knowledge; no live web search. |
  78. | `project_memory` | Manage projects, save research records, index user-approved local folders, and export graphs. |
  79. | `health` | Inspect search and local runtime status. |
  80. Providing `project_id` to web search does not make it local-only. Use `project_memory_search` for stored knowledge.
  81. [Tool parameters, limits, follow-up reads, and repeatable source collection](./guides/tools.md)
  82. ## Google Surf Auto Ontology
  83. <a href="./assets/graph-pkm.png"><img src="./assets/graph-pkm.png" width="100%" alt="Integrated project knowledge graph" /></a>
  84. Search and extraction results are saved automatically. Plans, experiments, failures, and decisions are linked when your agent records them through `project_memory`.
  85. Search stored knowledge across selected projects with exact-match, keyword, semantic, and graph retrieval, RRF fusion, and a shared reranker.
  86. 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.
  87. Create a standalone graph explorer for one project:
  88. ```text
  89. project_memory(action="export", project_id="my-project", export_format="html", export_view="graph")
  90. ```
  91. The HTML explorer includes PKM, lineage, and ontology views with PNG/JSON downloads. DOT and Neo4j exports are also available.
  92. The feature was renamed from Research to Auto Ontology; existing `SURF_RESEARCH*` settings, `project_memory*` tools, CLI names, and storage paths still work.
  93. [Ontology, lineage, code indexing, and export details](./guides/auto-ontology.md)
  94. ## Documentation
  95. | Guide | Contents |
  96. | --- | --- |
  97. | [Getting started](./guides/getting-started.md) | Installation, clients, browser search, SearchApi setup |
  98. | [Tools and workflows](./guides/tools.md) | Tool parameters, limits, evidence responses, source collection |
  99. | [Auto Ontology](./guides/auto-ontology.md) | Storage, code structure, graph retrieval, lineage, exports |
  100. | [Configuration](./guides/configuration.md) | Environment variables, resource settings, OrcaRouter |
  101. | [Operations and security](./guides/operations.md) | CAPTCHA, cache cleanup, CLI, privacy, optional Codex hooks |
  102. | [Benchmarks](./guides/benchmarks.md) | Measurements, conditions, and evaluation boundaries |
  103. [Contributing](./CONTRIBUTING.md) · [Changelog](./CHANGELOG.md) · [MIT License](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.