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等工具的集成