Google Search Tool

Google Search Tool

一个基于 Playwright 的 Node.js 工具，可绕过搜索引擎的反爬机制，执行 Google 搜索并提取结果。它既可作为命令行工具直接使用，也可作为 Model Context Protocol（MCP）服务，为 Claude 等 AI 助手提供实时搜索能力。

中文文档

主要功能

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

技术特性

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

安装

# Install from source
git clone https://github.com/web-agent-master/google-search.git
cd google-search
# Install dependencies
npm install
# Or using yarn
yarn
# Or using pnpm
pnpm install

# Compile TypeScript code
npm run build
# Or using yarn
yarn build
# Or using pnpm
pnpm build

# Link package globally (required for MCP functionality)
npm link
# Or using yarn
yarn link
# Or using pnpm
pnpm link

Windows 环境说明

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

1. 提供 .cmd 文件，确保命令行工具可在 Windows 命令提示符和 PowerShell 中正常运行
2. 日志文件存储在系统临时目录中，而非 Unix/Linux 的 /tmp 目录
3. 添加了 Windows 专用的进程信号处理，以确保服务正常关闭
4. 使用跨平台文件路径处理方式，以支持 Windows 路径分隔符

用法

命令行工具

# Direct command line usage
google-search "search keywords"

# Using command line options
google-search --limit 5 --timeout 60000 --no-headless "search keywords"

# Or using npx
npx google-search-cli "search keywords"

# Run in development mode
pnpm dev "search keywords"

# Run in debug mode (showing browser interface)
pnpm debug "search keywords"

# Get raw HTML of search result page
google-search "search keywords" --get-html

# Get HTML and save to file
google-search "search keywords" --get-html --save-html

# Get HTML and save to specific file
google-search "search keywords" --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."
    }
    // More results...
  ]
}

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 服务

此项目提供 Model Context Protocol（MCP）服务功能，让 Claude 等 AI 助手能够直接使用 Google 搜索功能。MCP 是一种开放协议，可让 AI 助手安全地访问外部工具和数据。

# Build the project
pnpm build

与 Claude Desktop 集成

1. 编辑 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 即可直接打开

2. 添加服务配置并重启 Claude

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

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

1. 使用 cmd.exe 和 npx：

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

2. 使用带完整路径的 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          # Project configuration and dependencies
├── tsconfig.json         # TypeScript configuration
├── src/
│   ├── index.ts          # Entry file (command line parsing and main logic)
│   ├── search.ts         # Search functionality implementation (Playwright browser automation)
│   ├── mcp-server.ts     # MCP server implementation
│   └── types.ts          # Type definitions (interfaces and type declarations)
├── dist/                 # Compiled JavaScript files
├── bin/                  # Executable files
│   └── google-search     # Command line entry script
├── README.md             # Project documentation
└── .gitignore            # Git ignore file

技术栈

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

开发指南

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

# Install dependencies
pnpm install

# Install Playwright browsers
pnpm run postinstall

# Compile TypeScript code
pnpm build

# Clean compiled output
pnpm clean

CLI 开发

# Run in development mode
pnpm dev "search keywords"

# Run in debug mode (showing browser interface)
pnpm debug "search keywords"

# Run compiled code
pnpm start "search keywords"

# Test search functionality
pnpm test

MCP 服务开发

# Run MCP server in development mode
pnpm mcp

# Run compiled MCP server
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 助手集成