# google-surf-mcp

This MCP server searches the web, papers, and code, then stores results in a local project knowledge graph. Use it for research and codebase discovery.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 291
- Author: HarimxChoi
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/HarimxChoi/google-surf-mcp
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/mcp/google-surf-mcp

## What it does

google-surf-mcp combines Google web search, academic papers, and GitHub repositories. Extracted results, plans, experiments, and decisions are stored in project-scoped memory. Retrieval runs exact search, BM25, vector search, code relations, and graph search independently before combining results with RRF and a shared reranker.

Research mode is enabled by default. The server exposes seven tools: `search`, `search_parallel`, `extract`, `scholar_search`, `project_memory_search`, `project_memory`, and `health`. Tree-sitter connects files, symbols, imports, and calls, while graph analysis can export HTML, Graphviz, D3 JSON, or Neo4j import data.

Browser search works without an API key and uses system Chrome; SearchApi can be added as a primary or fallback provider. Configuration accepts `SEARCH_API`, `SURF_SEARCH_PROVIDER`, `SURF_SCHOLAR_PROVIDER`, `SURF_BROWSER_ENGINE`, and `CHROME_PATH`. Browser mode depends on system Chrome unless another configured engine is used.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `SEARCH_API`, `SURF_SEARCH_PROVIDER`, `SURF_SCHOLAR_PROVIDER`, `SURF_BROWSER_ENGINE`, `CHROME_PATH`, `SURF_PROFILE_ROOT`, `SURF_RESEARCH`, `SURF_RETRIEVAL_MODE`, `SURF_RESEARCH_ROOT`, `SURF_RESEARCH_VECTOR_MODEL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env SEARCH_API=<SEARCH_API> --env SURF_SEARCH_PROVIDER=<SURF_SEARCH_PROVIDER> --env SURF_SCHOLAR_PROVIDER=<SURF_SCHOLAR_PROVIDER> --env SURF_BROWSER_ENGINE=<SURF_BROWSER_ENGINE> --env CHROME_PATH=<CHROME_PATH> --transport stdio google-surf-mcp -- npx -y google-surf-mcp
```
Replace <…> with your own values. 24 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add google-surf-mcp --env SEARCH_API=<SEARCH_API> --env SURF_SEARCH_PROVIDER=<SURF_SEARCH_PROVIDER> --env SURF_SCHOLAR_PROVIDER=<SURF_SCHOLAR_PROVIDER> --env SURF_BROWSER_ENGINE=<SURF_BROWSER_ENGINE> --env CHROME_PATH=<CHROME_PATH> -- npx -y google-surf-mcp
```
Replace <…> with your own values. 24 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "google-surf-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "google-surf-mcp"
            ],
            "env": {
                "SEARCH_API": "<SEARCH_API>",
                "SURF_SEARCH_PROVIDER": "<SURF_SEARCH_PROVIDER>",
                "SURF_SCHOLAR_PROVIDER": "<SURF_SCHOLAR_PROVIDER>",
                "SURF_BROWSER_ENGINE": "<SURF_BROWSER_ENGINE>",
                "CHROME_PATH": "<CHROME_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. 24 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "google-surf-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "google-surf-mcp"
            ],
            "env": {
                "SEARCH_API": "<SEARCH_API>",
                "SURF_SEARCH_PROVIDER": "<SURF_SEARCH_PROVIDER>",
                "SURF_SCHOLAR_PROVIDER": "<SURF_SCHOLAR_PROVIDER>",
                "SURF_BROWSER_ENGINE": "<SURF_BROWSER_ENGINE>",
                "CHROME_PATH": "<CHROME_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. 24 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e SEARCH_API=<SEARCH_API> -e SURF_SEARCH_PROVIDER=<SURF_SEARCH_PROVIDER> -e SURF_SCHOLAR_PROVIDER=<SURF_SCHOLAR_PROVIDER> -e SURF_BROWSER_ENGINE=<SURF_BROWSER_ENGINE> -e CHROME_PATH=<CHROME_PATH> google-surf-mcp npx -y google-surf-mcp
```
Replace <…> with your own values. 24 more environment variables are in the server README

## When to use it
- search web pages, papers, and GitHub repositories
- extract text and metadata from HTML and PDF files
- store research results in project memory
- trace relations between files, symbols, and calls
- export a local knowledge graph

## Example prompts
- Search for papers and repositories about distributed queues, then save the results to project memory.
- Extract the text and DOI from this PDF and link the source to the current project.
- Search the codebase for calls to `createClient` and show related files through the graph.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md