MCP 服务器

Google Search Tool

一个基于 Playwright 的 Node.js 工具，可以绕过搜索引擎的反爬虫机制来执行 Google 搜索。是 SERP API 的本地替代方案，并集成了 MCP 服务器。

web-agent-master

研究与数据

README

Google 搜索工具

一个基于 Playwright 的 Node.js 工具，可以绕过搜索引擎的反爬虫机制来执行 Google 搜索并提取结果。它可以直接用作命令行工具，也可以用作模型上下文协议 (MCP) 服务器，为像 Claude 这样的 AI 助手提供实时搜索能力。

中文文档

主要特性

本地 SERP API 替代方案: 无需依赖付费的搜索引擎结果 API 服务，所有搜索都在本地执行
高级反机器人检测绕过技术:
- 智能浏览器指纹管理，模拟真实用户行为
- 自动保存和恢复浏览器状态，减少验证频率
- 智能无头/有头模式切换，在需要验证时自动切换到有头模式
- 设备和区域设置的随机化，以降低检测风险
原始 HTML 检索: 能够获取搜索结果页面的原始 HTML（已删除 CSS 和 JavaScript），以便在 Google 的页面结构发生变化时进行分析和调试
页面截图: 在保存 HTML 内容时自动捕获并保存完整页面截图
MCP 服务器集成: 为像 Claude 这样的 AI 助手提供实时搜索能力，无需额外的 API 密钥
完全开源和免费: 所有代码都是开源的，没有使用限制，可以自由定制和扩展

技术特性

使用 TypeScript 开发，提供类型安全和更好的开发体验
基于 Playwright 的浏览器自动化，支持多种浏览器引擎
命令行参数支持搜索关键词
MCP 服务器支持 AI 助手集成
返回包含标题、链接和摘要的搜索结果
可选择检索搜索结果页面的原始 HTML 以进行分析
JSON 格式输出
支持无头和有头模式（用于调试）
详细的日志输出
强大的错误处理
浏览器状态保存和恢复，有效避免反机器人检测

安装

# 从源码安装
git clone https://github.com/web-agent-master/google-search.git
cd google-search
# 安装依赖
npm install
# 或者使用 yarn
yarn
# 或者使用 pnpm
pnpm install

# 编译 TypeScript 代码
npm run build
# 或者使用 yarn
yarn build
# 或者使用 pnpm
pnpm build

# 全局链接包（MCP 功能需要）
npm link
# 或者使用 yarn
yarn link
# 或者使用 pnpm
pnpm link

Windows 环境注意事项

此工具已针对 Windows 环境进行了专门适配：

提供 .cmd 文件以确保命令行工具在 Windows 命令提示符和 PowerShell 中正常工作
日志文件存储在系统临时目录中，而不是 Unix/Linux 的 /tmp 目录
添加了特定于 Windows 的进程信号处理，以确保服务器正确关闭
使用跨平台文件路径处理来支持 Windows 路径分隔符

使用方法

命令行工具

# 直接命令行使用
google-search "搜索关键词"

# 使用命令行选项
google-search --limit 5 --timeout 60000 --no-headless "搜索关键词"

# 或者使用 npx
npx google-search-cli "搜索关键词"

# 在开发模式下运行
pnpm dev "搜索关键词"

# 在调试模式下运行（显示浏览器界面）
pnpm debug "搜索关键词"

# 获取搜索结果页面的原始 HTML
google-search "搜索关键词" --get-html

# 获取 HTML 并保存到文件
google-search "搜索关键词" --get-html --save-html

# 获取 HTML 并保存到指定文件
google-search "搜索关键词" --get-html --save-html --html-output "./output.html"

命令行选项

-l, --limit <number>: 结果数量限制（默认：10）
-t, --timeout <number>: 超时时间，单位为毫秒（默认：60000）
--no-headless: 显示浏览器界面（用于调试）
--remote-debugging-port <number>: 启用远程调试端口（默认：9222）
--state-file <path>: 浏览器状态文件路径（默认：./browser-state.json）
--no-save-state: 不保存浏览器状态
--get-html: 检索搜索结果页面的原始 HTML，而不是解析结果
--save-html: 将 HTML 保存到文件（与 --get-html 一起使用）
--html-output <path>: 指定 HTML 输出文件路径（与 --get-html 和 --save-html 一起使用）
-V, --version: 显示版本号
-h, --help: 显示帮助信息

输出示例

{
  "query": "deepseek",
  "results": [
    {
      "title": "DeepSeek",
      "link": "https://www.deepseek.com/",
      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
    },
    {
      "title": "DeepSeek",
      "link": "https://www.deepseek.com/",
      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
    },
    {
      "title": "deepseek-ai/DeepSeek-V3",
      "link": "https://github.com/deepseek-ai/DeepSeek-V3",
      "snippet": "We present DeepSeek-V3, a strong Mixture-of-Experts (MoE) language model with 671B total parameters with 37B activated for each token."
    }
    // 更多结果...
  ]
}

HTML 输出示例

使用 --get-html 选项时，输出将包含有关 HTML 内容的信息：

{
  "query": "playwright automation",
  "url": "https://www.google.com/",
  "originalHtmlLength": 1291733,
  "cleanedHtmlLength": 456789,
  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\"><head><meta charset=\"UTF-8\"><meta content=\"dark light\" name=\"color-scheme\"><meta content=\"origin\" name=\"referrer\">..."
}

如果同时使用 --save-html 选项，输出将包含 HTML 的保存路径：

{
  "query": "playwright automation",
  "url": "https://www.google.com/",
  "originalHtmlLength": 1292241,
  "cleanedHtmlLength": 458976,
  "savedPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.html",
  "screenshotPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.png",
  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\">..."
}

MCP 服务器

此项目提供模型上下文协议 (MCP) 服务器功能，允许像 Claude 这样的 AI 助手直接使用 Google 搜索功能。 MCP 是一种开放协议，使 AI 助手能够安全地访问外部工具和数据。

# 构建项目
pnpm build

与 Claude Desktop 集成

编辑 Claude Desktop 配置文件：
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
  - 通常位于 C:\Users\username\AppData\Roaming\Claude\claude_desktop_config.json
  - 您可以通过在 Windows 资源管理器的地址栏中输入 %APPDATA%\Claude 直接访问它
添加服务器配置并重启 Claude

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

对于 Windows 环境，您还可以使用以下配置：

使用 cmd.exe 和 npx：

{
  "mcpServers": {
    "google-search": {
      "command": "cmd.exe",
      "args": ["/c", "npx", "google-search-mcp"]
    }
  }
}

使用 node 和完整路径（如果上述方法遇到问题，建议使用此方法）：

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["C:/path/to/your/google-search/dist/src/mcp-server.js"]
    }
  }
}

注意：对于第二种方法，您必须将 C:/path/to/your/google-search 替换为您安装 google-search 包的实际完整路径。

集成后，您可以直接在 Claude 中使用搜索功能，例如“搜索最新的 AI 研究”。

项目结构

google-search/
├── package.json          # 项目配置和依赖
├── tsconfig.json         # TypeScript 配置
├── src/
│   ├── index.ts          # 入口文件（命令行解析和主逻辑）
│   ├── search.ts         # 搜索功能实现（Playwright 浏览器自动化）
│   ├── mcp-server.ts     # MCP 服务器实现
│   └── types.ts          # 类型定义（接口和类型声明）
├── dist/                 # 编译后的 JavaScript 文件
├── bin/                  # 可执行文件
│   └── google-search     # 命令行入口脚本
├── README.md             # 项目文档
└── .gitignore            # Git 忽略文件

技术栈

TypeScript: 开发语言，提供类型安全和更好的开发体验
Node.js: 用于执行 JavaScript/TypeScript 代码的运行时环境
Playwright: 用于浏览器自动化，支持多种浏览器
Commander: 用于解析命令行参数和生成帮助信息
模型上下文协议 (MCP): 用于 AI 助手集成的开放协议
MCP SDK: 用于实现 MCP 服务器的开发工具包
Zod: 用于验证和类型安全的模式定义库
pnpm: 高效的包管理工具，节省磁盘空间和安装时间

开发指南

所有命令都可以在项目根目录中运行：

# 安装依赖
pnpm install

# 安装 Playwright 浏览器
pnpm run postinstall

# 编译 TypeScript 代码
pnpm build

# 清理编译输出
pnpm clean

CLI 开发

# 在开发模式下运行
pnpm dev "搜索关键词"

# 在调试模式下运行（显示浏览器界面）
pnpm debug "搜索关键词"

# 运行编译后的代码
pnpm start "搜索关键词"

# 测试搜索功能
pnpm test

MCP 服务器开发

# 在开发模式下运行 MCP 服务器
pnpm mcp

# 运行编译后的 MCP 服务器
pnpm mcp:build

错误处理

该工具内置了强大的错误处理机制：

浏览器启动失败时的友好错误消息
网络连接问题时的自动错误状态返回
搜索结果解析失败时的详细日志
超时情况下的正常退出和有用的信息返回

注意事项

一般注意事项

此工具仅用于学习和研究目的
请遵守 Google 的服务条款和政策
不要过于频繁地发送请求，以避免被 Google 阻止
某些地区可能需要代理才能访问 Google
Playwright 需要安装浏览器，首次使用时会自动下载

状态文件

状态文件包含浏览器 cookie 和存储数据，请妥善保管
使用状态文件可以有效避免 Google 的反机器人检测，提高搜索成功率

MCP 服务器

MCP 服务器需要 Node.js v16 或更高版本
使用 MCP 服务器时，请确保 Claude Desktop 已更新到最新版本
配置 Claude Desktop 时，请使用 MCP 服务器文件的绝对路径

Windows 特定注意事项

在 Windows 环境中，您可能需要管理员权限才能首次安装 Playwright 浏览器
如果遇到权限问题，请尝试以管理员身份运行命令提示符或 PowerShell
Windows 防火墙可能会阻止 Playwright 浏览器网络连接；出现提示时允许访问
浏览器状态文件默认保存在用户主目录中，文件名为 .google-search-browser-state.json
日志文件存储在系统临时目录下的 google-search-logs 文件夹中

与商业 SERP API 的比较

与付费的搜索引擎结果 API 服务（例如 SerpAPI）相比，此项目具有以下优势：

完全免费: 无 API 调用费用
本地执行: 所有搜索都在本地执行，不依赖第三方服务
隐私保护: 搜索查询不会被第三方记录
可定制性: 完全开源，可以根据需要进行修改和扩展
无使用限制: 不受 API 调用次数或频率限制
MCP 集成: 原生支持与像 Claude 这样的 AI 助手集成

Google Search Tool

README

Google 搜索工具

主要特性

技术特性

安装

Windows 环境注意事项

使用方法

命令行工具

命令行选项

输出示例

HTML 输出示例

MCP 服务器

与 Claude Desktop 集成

项目结构

技术栈

开发指南

CLI 开发

MCP 服务器开发

错误处理

注意事项

一般注意事项

状态文件

MCP 服务器

Windows 特定注意事项

与商业 SERP API 的比较

推荐服务器