google-surf-mcp

✨反机器人搜索 MCP：无需 API 密钥✨

English | 한국어

仅供演示。实际搜索默认在 无头模式 (headless) 下运行（无可见浏览器）。设置 SURF_HEADLESS=false 可使 Chrome 可见，如上图所示。

Google 搜索 MCP。无需 API 密钥。开箱即用。

• ✅ 确实有效（测试了 6 个免费的 Google 搜索 MCP，全部失败）

• ✅ 在一个 MCP 中完成搜索 + URL 提取（取代了通常的“搜索 MCP + 获取 MCP”组合）

• ✅ 4 个工具：search / search_parallel / extract / search_extract

• ✅ 无需 API 密钥，无需代理，无需验证码破解服务

• ✅ 自动验证码恢复（打开 Chrome，人工解决一次，调用自动重试）

• ✅ extract 上的 SSRF 防护（默认阻止 localhost、私有 IP 和 AWS 元数据）

简介

将其插入任何 MCP 客户端，即可获得 Google 搜索工具。

无需验证码破解服务。当任何工具触发验证码时，会打开一个 Chrome 窗口供人工解决。每次解决都会保留该配置文件在 Google 处的信誉。专为可持续、合乎道德的使用而构建。

首次安装需要约 1 秒的配置文件预热（见安装）。

专为本地使用设计。不适用于无状态/无服务器部署。

Related MCP server: Brave Search MCP Server

性能数据

在 1Gb/s 连接的工作站上测量。

技术栈

• Playwright + 持久化 Chrome 配置文件

• playwright-extra 隐身模式

• 屏蔽图片/媒体/字体资源以提高速度

• 首次运行前的一次性配置文件引导

• Mozilla Readability + Turndown 用于文章提取

安装

需要 Node 18+ 和系统上的 Google Chrome（或 Chromium）。

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

或本地克隆：

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

bootstrap 会打开一个 Chrome 窗口。在其中运行一次 Google 搜索。关闭。配置文件现已预热。

如有需要，可覆盖路径：

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

与 Claude Code 一起使用

将其粘贴到你的 ~/.claude.json 中：

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"]
    }
  }
}

重启 Claude Code。完成。search、search_parallel、extract、search_extract 现已可用。

对于其他 MCP 客户端，请在其配置文件中使用相同的 JSON 格式。

本地克隆变体：

{
  "mcpServers": {
    "google-surf": {
      "command": "node",
      "args": ["/abs/path/to/google-surf-mcp/build/index.js"]
    }
  }
}

工具

• search(query, limit?) - 单次查询，约 1.5秒。返回标题/URL/摘要。过滤掉赞助广告。

• search_parallel(queries[], limit?) - 4 个并发池，每次调用最多 10 个查询。

• extract(url, max_chars?) - 获取 URL，返回文章 Markdown（Readability 配合文本回退）。失败返回 { error }，从不抛出异常。

• search_extract(query, limit?, max_chars?) - 单次调用完成搜索 + 并行提取。返回包含完整文章内容的 SERP 结果。页面级失败是隔离的。

search_extract 是杀手级功能：单次调用即可获得 SERP + 完整文章内容。取代了大多数代理拼凑的“搜索 MCP + URL 获取器 MCP”组合。

环境变量

故障排除

• 验证码：会自动打开一个可见的 Chrome 窗口（适用于所有 4 个工具）。解决一次，在里面做一次搜索，调用会自动重试并继续。如果想快速失败，请在无显示器连接的环境下运行。

• “Chrome not found”：安装 Chrome 或设置 CHROME_PATH。

• 过时的选择器：Google 会轮换类名。欢迎提交 PR。

更新日志

见 CHANGELOG.md。

许可证

MIT