AI导哈

谷歌搜索工具

一个基于Playwright的Node.js工具，用于绕过搜索引擎的反爬机制执行谷歌搜索并提取结果，可作为命令行工具或MCP服务器为AI助手提供实时搜索能力。

  • by ACSGenUI
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 ACSGenUI/mcp-google-search

使用说明

谷歌搜索工具

一个基于Playwright的Node.js工具，绕过搜索引擎的反抓取机制来执行谷歌搜索并提取结果。它可以直接用作命令行工具或模型上下文协议（MCP）服务器，为Claude等AI助手提供实时搜索功能。

主要特点

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

技术特性

  • 使用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"

可用命令行选项

  • --limit <number>：限制结果数量（默认值：10）
  • --timeout <number>：设置超时时间（毫秒）（默认值：30000）
  • --no-headless: 已弃用：该工具现在总是以无头模式启动，如果遇到验证码验证，会自动切换到有头模式
  • --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)

MCP服务器使用情况

配置

将以下配置添加到MCP设置文件中（例如。， ~/.cursor/mcp.json 或克劳德桌面配置）：

{
  "mcpServers": {
    "google-search": {
      "command": "google-search-mcp"
    }
  }
}

配置后，重新启动您的AI助手（Claude Desktop或Cursor）以启用Google搜索工具。

如何在AI助手中使用

配置后，您可以直接要求AI助手搜索信息：

  • “搜索有关TypeScript 5.0的最新信息”
  • “查找有关使用Playwright的教程”
  • “人工智能的最新发展是什么？”

人工智能助手将自动调用谷歌搜索工具，从网络上检索实时信息，并根据搜索结果提供答案。

输出格式

标准搜索结果

{
  "query": "search keywords",
  "results": [
    {
      "title": "Result title",
      "link": "https://example.com",
      "snippet": "Result summary..."
    }
  ]
}

HTML检索结果

使用时 --get-html 选项：

{
  "query": "search keywords",
  "url": "https://www.google.com/search?q=...",
  "originalHtmlLength": 123456,
  "cleanedHtmlLength": 78900,
  "savedPath": "./google-search-html/query-timestamp.html",
  "screenshotPath": "./google-search-html/query-timestamp.png",
  "htmlPreview": "First 500 characters of HTML..."
}

浏览器状态管理

此工具会自动保存浏览器状态，以避免重复验证码验证：

  1. 首次运行：如果遇到验证码验证，该工具将自动切换到头部模式（可见浏览器）并等待您完成验证
  2. 国家储蓄：验证成功后，浏览器状态会自动保存到 ~/.google-search-browser-state.json （适用于MCP服务器）或当前目录 browser-state.json （用于命令行工具）
  3. 后续运行：该工具使用保存的状态绕过验证，实现快速无头搜索
  4. 指纹管理：浏览器指纹配置会自动保存并重复使用，以降低检测风险

技术细节

反机器人检测策略

该工具使用多种技术绕过谷歌的反机器人检测：

  1. 浏览器指纹模拟:

    • 自动检测并使用主机的时区、语言和其他设置
    • 随机化设备类型（桌面Chrome、Firefox、Safari、Edge）
    • 模拟真实的浏览器环境（WebGL、插件、屏幕分辨率等）

  2. 行为仿真:

    • 随机延迟模拟人类输入速度
    • 使用真实的键盘事件而不是直接设置值
    • 保持一致的行为模式

  3. 状态持久性:

    • 保存和恢复Cookie和本地存储
    • 保持一致的浏览器指纹
    • 通过重用会话降低验证频率

  4. 智能模式切换:

    • 以无头模式启动，以获得最佳性能
    • 检测到验证码时自动切换到头部模式
    • 提示用户完成验证，然后保存状态以备将来使用

日志记录

所有日志都保存到系统临时目录：

  • Unix/Linux/macOS： /tmp/google-search-logs/google-search.log
  • 窗户： %TEMP%\google-search-logs\google-search.log

日志级别可以通过以下方式控制 LOG_LEVEL 环境变量：

LOG_LEVEL=debug google-search "search keywords"

发展

# Install dependencies
pnpm install

# Compile TypeScript
pnpm build

# Run in development mode
pnpm dev "search keywords"

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

# Run MCP server
pnpm mcp

# Test build
pnpm test:build

故障排除

验证码验证问题

如果您经常遇到验证码验证：

  1. 让工具自动切换到头部模式并完成验证
  2. 确保浏览器状态文件已正确保存
  3. 尝试使用不同的谷歌域名（该工具会自动随机化）
  4. 避免在短时间内提出太多请求

剧作家安装问题

如果Playwright浏览器安装失败：

# Manually install Chromium
npx playwright install chromium

# Or install all browsers
npx playwright install

权限问题

在Unix/Linux系统上，如果遇到权限问题：

# Make bin files executable
chmod +x bin/google-search
chmod +x bin/google-search-mcp

贡献

欢迎问题和拉取请求！请确保代码遵循现有样式，并且所有测试都通过。

许可证

ISC许可证

鸣谢

该项目由以下人员维护 web代理主机.

相关项目

相关 MCP