google-search

🚀 谷歌搜索工具使用指南

本谷歌搜索工具为开发者提供了便捷的搜索功能，可在本地运行，支持多种模式，还具备强大的错误处理机制，能有效帮助用户进行搜索相关的学习和研究。

🚀 快速开始

在使用该工具前，你需要先完成安装步骤，之后就可以按照不同的需求运行相应的命令进行搜索操作。

📦 安装指南

请在项目根目录下运行以下命令完成工具的安装与配置：

# 安装依赖项
pnpm install

# 安装Playwright浏览器
pnpm run postinstall

# 编译TypeScript代码
pnpm build

# 清理编译输出
pnpm clean

💻 使用示例

基础用法

所有命令均可在项目根目录下运行：

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

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

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

# 测试搜索功能
pnpm test

高级用法

MCP服务器开发

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

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

🔧 技术细节

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

• 浏览器启动失败时显示友好的错误消息
• 网络连接问题自动返回错误状态
• 搜索结果解析失败时记录详细日志
• 超时情况下的优雅退出并提供有用信息

📚 详细文档

注意事项

通用注意事项

⚠️ 重要提示

• 本工具仅用于学习和研究目的
• 请遵守Google的服务条款和政策
• 请勿频繁发送请求以免被Google封禁
• 某些地区可能需要使用代理访问Google
• Playwright会自动下载浏览器，首次使用时可能会占用带宽

状态文件注意事项

⚠️ 重要提示

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

MCP服务器注意事项

⚠️ 重要提示

• MCP服务器要求Node.js v16或更高版本
• 配置Claude桌面端时请确保使用最新版本
• 配置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等工具的集成