google-surf-mcp — Claude Code MCP server: search and install
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.
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-mcpWhat google-surf-mcp 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.
What it helps with
- 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 for the agent
- 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
createClientand show related files through the graph.
How to install google-surf-mcp
Platform CLI
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-mcpReplace <…> with your own values. 24 more environment variables are in the server README
Platform CLI
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-mcpReplace <…> with your own values. 24 more environment variables are in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values. 24 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about google-surf-mcp
How do I install google-surf-mcp in Claude Code?
Run `claude mcp add google-surf-mcp -e SEARCH_API=<SEARCH_API> -e GITHUB_TOKEN=<GITHUB_TOKEN> -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e ORCAROUTER_API_KEY=<ORCAROUTER_API_KEY> -- npx -y google-surf-mcp`.
What does google-surf-mcp do?
It searches web sources, academic papers, and code, extracts content, and stores it in a local project knowledge graph. Retrieval combines fresh results with accumulated project memory.
Does browser search require an API key?
No. Browser search uses system Chrome without an API key, while SearchApi can be configured as a primary or fallback provider.
