使用说明

谷歌搜索工具

一个基于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环境进行了调整：

.cmd 提供文件以确保命令行工具在Windows命令提示符和PowerShell中正常工作
日志文件存储在系统临时目录中，而不是Unix/Linux /tmp 目录
已添加特定于Windows的进程信号处理，以确保正确关闭服务器
跨平台文件路径处理用于支持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输出文件路径（与--gethtml和--savehtml一起使用）
-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服务器

该项目提供模型上下文协议（MCP）服务器功能，允许像克劳德这样的人工智能助手直接使用谷歌搜索功能。MCP是一种开放协议，使AI助手能够安全地访问外部工具和数据。

# Build the project
pnpm build

与Claude Desktop集成

编辑Claude Desktop配置文件：
- 雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json
  - 通常位于 C:\Users\username\AppData\Roaming\Claude\claude_desktop_config.json
  - 您可以通过输入直接访问它 %APPDATA%\Claude 在Windows资源管理器地址栏中
添加服务器配置并重新启动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"]
    }
  }
}

使用具有完整路径的节点（如果您遇到上述方法的问题，建议使用）：

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

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

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

项目结构

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代码的运行时环境
剧作家：用于浏览器自动化，支持多个浏览器
指挥官：用于解析命令行参数和生成帮助信息
模型上下文协议（MCP）：AI助手集成的开放协议
MCP-SDK：用于实施MCP服务器的开发工具包
萨德：用于验证和类型安全的模式定义库
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

错误处理

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

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

备注

一般注意事项

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

状态文件

州文件包含浏览器Cookie和存储数据，请确保其安全
使用状态文件可以有效避免谷歌的反机器人检测，提高搜索成功率

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

使用说明

谷歌搜索工具

主要特点

技术特性

安装

Windows环境说明

用法

命令行工具

命令行选项

输出示例

HTML输出示例

MCP服务器

与Claude Desktop集成

项目结构

技术栈

开发指南

CLI开发

MCP服务器开发

错误处理

备注

一般注意事项

状态文件

MCP服务器

Windows特定注意事项

与商业SERP API的比较

相关 MCP

浏览器自动化MCP服务

浏览器自动化MCP服务器

网页内容抓取服务

Playwright浏览器自动化服务器

iOS模拟器交互服务器

网页搜索MCP服务器