# Google Surf MCP: A Local Knowledge Graph for Search, Papers, and Code

> Google Surf MCP turns web searches, academic papers, and codebases into a project-scoped knowledge graph for AI agents. It runs without API keys or external servers, but its browser-based search and embedded database carry real operational costs.

**HarimxChoi/google-surf-mcp** — Turn Google Search, Papers, and Codebases into an Automatic Local Knowledge Graph for AI Agents.

- Repository: https://github.com/HarimxChoi/google-surf-mcp
- Stars: 291 · Forks: 34
- Language: TypeScript
- License: MIT
- Published: 2026-08-27 · Updated: 2026-08-27 · Language: en
- Canonical page: https://hysenlabs.com/projects/harimxchoi-google-surf-mcp

## What Problem It Solves and Who It Is For

Google Surf MCP addresses a specific pain: AI agents that search the web repeatedly often lose context, repeat queries, and cannot trace the provenance of a claim. This project stores every search, extracted paper, and codebase scan into a local, project-scoped knowledge graph. It is meant for developers building MCP-based agents that need durable research memory, such as a research assistant that accumulates findings over multiple sessions. The target user is someone who wants zero API keys and zero external servers, meaning no paid search API and no separate Neo4j instance. The README's tagline, 'Turn Google Search, Papers, and Codebases into an Automatic Local Knowledge Graph and lineage for AI Agents with Zero API Key, Zero External Server,' captures the core promise. It is not for casual users; it requires Node.js, Chrome, and a willingness to manage an embedded database.

## How It Works: Hybrid Retrieval and Project Memory

The mechanism is a multi-stage pipeline. Live web results, papers, codebases, and project memory are searched independently using exact match, BM25, vector search, code graph search, and graph PPR. These candidate sets are then combined using Reciprocal Rank Fusion (RRF) and a single shared reranker. The output includes evidence and provenance paths, which trace from source through documents, chunks, symbols, evidence, and assertions. The knowledge graph is built automatically: search results and extracted bodies become entities and relations, with typed nodes for web sources, papers, code, plans, experiments, and decisions. Projects are isolated by default, but cross-project links are added only when verifiable, such as matching DOIs or repository URLs. This design avoids merging unrelated records while allowing reuse of knowledge across projects. The graph analysis runs locally using Graphology, so PageRank, PPR, and Louvain communities do not need a separate server.

## Getting It Running: Commands and Configuration

The installation is straightforward for an MCP server. You need Node.js 20.18.1 or later and Google Chrome or Chromium. The primary command is `npx google-surf-mcp`, which you register in your MCP client config. For Claude Code, you paste a JSON block into `~/.claude.json` with the command `npx -y google-surf-mcp`. The first tool call auto-bootstraps a warm Chrome profile, which may open a browser briefly. If that fails, run `npm run bootstrap` manually. You can override paths and timezone with environment variables, for example `CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap`. The server exposes seven tools by default: `search`, `search_parallel`, `extract`, `scholar_search`, `project_memory_search`, `project_memory`, and `health`. There is also a research mode, enabled by default, which opens the database and graph sidecar. Setting `SURF_RESEARCH=false` disables the project memory tools entirely, which is useful if you only want search and extraction without the storage overhead.

## Search and Extraction: Browser-Based, No API Key

The search component relies on system Chrome and the Chrome DevTools Protocol (CDP), with a Playwright compatibility fallback. It creates a dedicated logged-out profile that never reads or copies the user's Chrome profile, which addresses privacy concerns. The SERP parsing uses multiple strategies with geometric verification, and it removes sponsored blocks and knowledge panels. CAPTCHA detection and environment-specific recovery are built in, along with parser self-healing and context fallback. Extraction uses Mozilla Readability for HTML and LiteParse/PDFium for PDFs, with optional OCR and `pdf-lib` for metadata. The README provides measured latency: `search` takes 4.0 to 5.1 seconds per query, and `scholar_search` takes 3.8 to 5.6 seconds, measured on a workstation with a 1 Gb/s connection. These numbers are not benchmarks we reproduced; they are the project's own figures. The speed is not impressive, but the trade-off is that you avoid API costs and external dependencies.

## Codebase Search and Graph Analysis

For code, Google Surf MCP uses Tree-sitter to parse files, symbols, imports, and call relations from local project roots and gated GitHub sparse downloads. The code search combines exact lookup, BM25, Multilingual E5 vector search, and graph PPR. This means you can search for a function name or a concept and get results that are grounded in the actual call graph. The graph analysis includes PageRank, PPR, connected components, and Louvain communities, all computed locally with Graphology. You can export the graph to HTML, Graphviz, D3 JSON, and Neo4j import formats. The README shows an example export command: `project_memory(action="export", export_format="html", export_view="graph", all_projects=true)`. This is a strong feature for developers who want to visualize how their agent's knowledge is structured. However, the complexity here is high: the project bundles a full graph database, a vector index, and a code parser, which is a lot of moving parts for a single MCP server.

## Limitations and Failure Modes

The most obvious limitation is speed. At 4 to 5 seconds per query, this is not a real-time search tool. If your agent needs fast, interactive lookups, this will feel sluggish. The browser dependency is another risk: the search relies on system Chrome and CDP, and the CAPTCHA recovery is only as good as the heuristics. On a network with aggressive CAPTCHAs, the recovery may fail, and the fallback to SearchApi requires an API key, which contradicts the zero-key promise for those cases. The embedded SurrealDB on RocksDB means storage grows with every search and extraction. There is no mention of automatic cleanup or size limits, so long-running projects could accumulate significant disk usage. The research mode is on by default, which opens the database and graph sidecar on every invocation; if you only want a quick search, you must set `SURF_RESEARCH=false` and lose the project memory tools. The README also notes that the auto-bootstrap can fail, though it is described as rare. These are not fatal flaws, but they are real trade-offs.

## Alternatives and How They Differ

A direct alternative is to use a hosted search API like SearchApi or SerpAPI with a simple MCP server that stores results in a vector database. The difference is architectural: Google Surf MCP embeds the graph and retrieval into a single server, while a hosted API approach keeps search external and requires you to build the memory layer yourself. Another alternative is to use a general-purpose MCP server like `mcp-server-memory` with a vector store, but that lacks the codebase parsing and graph analysis. The key difference is that Google Surf MCP combines web, papers, and code into one unified graph with lineage, which most alternatives do not offer. However, that integration comes at the cost of complexity. If you only need web search and do not care about code or papers, a simpler tool would be faster and easier to maintain. The project's own sponsor, SearchApi, offers a hosted API that could replace the browser-based search, but then you lose the zero-key benefit.

## Maintenance and License Considerations

The project is MIT-licensed, which means you can use, modify, and distribute it freely, with attribution. There are no copyleft obligations, so it is safe for commercial use. The repository shows recent activity, with the latest release v1.0.0 on August 28, 2026, and a CI workflow. However, the project is relatively new, with only a few releases in the same week, so the API may change. The README does not document a migration path or upgrade notes, so you should pin the version in your `package.json` or use `npx -y` with a specific version. The maintenance cost is non-trivial: you must keep Node.js and Chrome updated, handle browser profile bootstrapping, and monitor the embedded database for growth. The project's own recovery mechanisms, such as parser self-healing, reduce some of that burden, but they are not a substitute for active maintenance. Before adopting, check the repository's issue tracker and recent commits to see how responsive the maintainer is to bugs.

## Conclusion

Adopt Google Surf MCP if you need a self-contained, project-scoped knowledge base for AI agents that combines live web, papers, and code without API keys or external graph servers. Skip it if your searches must be fast and predictable, or if you cannot tolerate Chrome-dependent behavior and the storage overhead of an embedded SurrealDB. Before adopting, verify the CAPTCHA recovery path on your network, test the bootstrap on your Chrome version, and confirm that the project memory tools are registered in your MCP client. The project is MIT-licensed and actively maintained, but its last push is August 2026, so check the repository for recent changes before committing.

## FAQ

### What does google-surf-mcp need in order to run?

Node 20.18.1 or later, and a copy of Chrome or Chromium for browser mode. You can run it through the package runner, or clone and install, and the first tool call auto-bootstraps a warm profile, so you may see the browser open briefly.

### What is SURF_RESEARCH and what does turning it off change?

Research mode and automatic capture are on by default, opening the local database and the graph sidecar and storing what it finds. Setting the variable to false gives search and extraction with neither opened, and the project memory tools are then not registered at all. Live results still pass through a lightweight in-memory reranker that needs no vector model.

### What does the google-surf-mcp reranker check actually show?

Over thirty-two held-out queries, the provider's own order scores 0.8949 for normalised gain at five, 0.8203 mean reciprocal rank and 0.6375 precision at five, while adding term matching with rank fusion gives 0.8971, 0.8203 and 0.6500. Mean reciprocal rank is unchanged, so the documented benefit is payload size rather than ranking quality.

### How does google-surf-mcp search without an API key?

It drives a system Chrome instance over the browser debugging protocol using a dedicated logged-out profile that never reads or copies your personal Chrome profile. Around that sit multi-strategy results-page parsing with geometric verification, removal of sponsored blocks and knowledge panels, captcha detection with environment-specific recovery, and a parser that self-heals.

### Can knowledge move between projects in google-surf-mcp?

Projects are isolated by default, and selected projects can be searched together. Only verifiable links cross the boundary, of three kinds: a matching digital object identifier, a repository URL, or an explicit alias, and a link does not merge the original records.

## Sources

- [Official README](https://github.com/HarimxChoi/google-surf-mcp#readme)
- [Project repository](https://github.com/HarimxChoi/google-surf-mcp)
- [Release notes](https://github.com/HarimxChoi/google-surf-mcp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/harimxchoi-google-surf-mcp