谷歌搜索

Name: 谷歌搜索
Author: web-agent-master

作者：web-agent-master499 星标更新：2025-04-06

安装使用来源：spider==github.com

项目介绍

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 现已上线并开源，与 OpenAI 的 Model o1 相媲美。可在网页、应用和 API 上使用。点击查看详情。深入..."
    },
    {
      "title": "DeepSeek",
      "link": "https://www.deepseek.com/",
      "snippet": "DeepSeek-R1 现已上线并开源，与 OpenAI 的 Model o1 相媲美。可在网页、应用和 API 上使用。点击查看详情。深入..."
    },
    {
      "title": "deepseek-ai/DeepSeek-V3",
      "link": "https://github.com/deepseek-ai/DeepSeek-V3",
      "snippet": "我们推出了 DeepSeek-V3，这是一个强大的混合专家（MoE）语言模型，总参数量为 671B，每个令牌激活 37B。"
    }
    // 更多结果...
  ]
}

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 助手集成。