🚀 谷歌搜索工具使用指南
本谷歌搜索工具为开发者提供了便捷的搜索功能，可在本地运行，支持多种模式，还具备强大的错误处理机制，能有效帮助用户进行搜索相关的学习和研究。
🚀 快速开始
在使用该工具前，你需要先完成安装步骤，之后就可以按照不同的需求运行相应的命令进行搜索操作。
📦 安装指南
请在项目根目录下运行以下命令完成工具的安装与配置：
# 安装依赖项
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等工具的集成