谷歌搜索工具
一个基于Playwright的Python工具，绕过搜索引擎的反抓取机制来执行谷歌搜索并提取结果。它可以直接用作命令行工具或模型上下文协议（MCP）服务器，为Claude等AI助手提供实时搜索功能。
主要特点
- 当地SERP API备选方案：无需依赖付费搜索引擎结果API服务，所有搜索都在本地执行
- 高级反机器人检测绕过技术:
- 模拟真实用户行为的智能浏览器指纹管理 - 自动保存和恢复浏览器状态，以减少验证频率 - 智能无头/有头模式切换，需要验证时自动切换到有头模式 - 随机化设备和区域设置以降低检测风险
- 原始HTML检索：当谷歌的页面结构发生变化时，能够获取搜索结果页面的原始HTML（删除CSS和JavaScript）进行分析和调试
- 页面截图：保存HTML内容时自动捕获并保存整页屏幕截图
- MCP服务器集成：为Claude等人工智能助手提供实时搜索功能，无需额外的API密钥
- 完全开源和免费：所有代码都是开源的，没有使用限制，可自由定制和扩展
- Python原生：使用Python构建，性能更好，部署更容易
技术特性
- 使用Python 3.8开发+，提供卓越的性能和广泛的兼容性
- 基于的浏览器自动化 剧作家，支持多种浏览器引擎
- 搜索关键字的命令行参数支持
- MCP服务器支持 用于AI助手集成
- 返回带有标题、链接和代码段的搜索结果
- 检索搜索结果页面的原始HTML进行分析的选项
- JSON格式输出
- 支持无头和有头模式（用于调试）
- 详细的测井输出
- 稳健的错误处理
- 浏览器状态保存和恢复，有效避免反机器人检测
- 反机器人保护机制 在多个层面
安装
# Install from source
git clone https://github.com/iwanghc/mcp_web_search.git
cd mcp_web_search
# Install Python dependencies
pip install -r requirements.txt
# Install Playwright browsers
playwright install chromium用法
命令行工具
# Direct command line usage
python cli.py "search keywords"
# Using command line options
python cli.py --limit 5 --timeout 30000 "search keywords"
# Get raw HTML of search result page
python cli.py --get-html "search keywords"
# Get HTML and save to file
python cli.py --get-html --save-html "search keywords"MCP服务器
# Configure model API KEY and other information in dotenv.env
# USE MCP server
python -m mcp_integration.client命令行选项
-l, --limit：结果计数限制（默认值：10）-t, --timeout：超时时间（毫秒）（默认值：30000）--no-headless：显示浏览器界面（用于调试）--remote-debugging-port：启用远程调试端口（默认值：9222）- `--state-file
`：浏览器状态文件路径（默认：./Browser state.json）
--no-save-state：不保存浏览器状态--get-html：获取搜索结果页面的原始HTML，而不是解析结果--save-html：将HTML保存到文件（与--get.HTML一起使用）- `--html-output
`：指定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": "..."
}如果你也使用 --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": "..."
}MCP服务器
该项目提供模型上下文协议（MCP）服务器功能，允许像克劳德这样的人工智能助手直接使用谷歌搜索功能。MCP是一种开放协议，使AI助手能够安全地访问外部工具和数据。
与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": "python",
"args": ["mcp_server_simple.py"]
}
}
}集成后，您可以直接使用Claude中的搜索功能，例如“搜索最新的人工智能研究”。
项目结构
google-search/
├── Core Functions/
│ ├── google_search/
│ │ ├── engine.py # Search engine implementation
│ │ ├── browser_manager.py # Browser management and automation
│ │ ├── search_executor.py # Search execution logic
│ │ ├── html_extractor.py # HTML parsing and extraction
│ │ ├── fingerprint.py # Browser fingerprint management
│ │ ├── utils.py # Utility functions
│ │ └── __init__.py # Package initialization
│ └── cli.py # Command line interface
├── MCP Integration/
│ ├── mcp_integration/
│ │ ├── server.py # MCP server implementation
│ │ ├── client.py # MCP client implementation
│ │ └── __init__.py # Package initialization
├── Common Utilities/
│ ├── common/
│ │ ├── logger.py # Logging system
│ │ ├── types.py # Common data types
│ │ └── __init__.py # Package initialization
├── Configuration & Runtime/
│ ├── requirements.txt # Python dependencies
│ ├── dotenv.env # Environment variables
│ ├── browser-state.json # Browser state persistence
│ ├── browser-state-fingerprint.json # Browser fingerprint data
│ └── .gitignore # Git ignore rules
├── Documentation/
│ ├── README.md # English documentation
│ ├── README.zh-CN.md # Chinese documentation
│ └── google_search/REFACTOR_README.md # Refactoring notes
├── Development/
│ ├── .vscode/ # VS Code configuration
│ └── logs/ # Application logs
└── Other/
└── __pycache__/ # Python cache files技术栈
- Python 3.8+：开发语言，提供卓越的性能和兼容性
- 剧作家：用于浏览器自动化，支持多个浏览器
- MCP-SDK：用于实施MCP服务器开发工具
- 异步IO：Python异步I/O标准库
- aiofiles：异步文件操作
开发指南
所有命令都可以在项目根目录中运行：
# Install dependencies
pip install -r requirements.txt
# Install Playwright browsers
playwright install chromium
# Run CLI tool
python cli.py "search keywords"
# Start MCP server
python mcp_server_simple.py
# Test MCP client
python mcp_client_enhanced.py错误处理
该工具内置了强大的错误处理机制：
- 浏览器启动失败时提供友好的错误信息
- 发生网络连接问题时自动返回错误状态
- 搜索结果解析失败时提供详细日志
- 在超时情况下优雅地退出并返回有用信息
备注
一般注意事项
- 此工具仅用于学习和研究目的
- 请遵守谷歌的服务条款和政策
- 不要过于频繁地发送请求，以免被谷歌屏蔽
- 某些地区可能需要代理才能访问谷歌
- Playwright需要安装浏览器，首次使用时会自动下载
状态文件
- 状态文件包含浏览器Cookie和存储数据，请确保其安全
- 使用状态文件可以有效避免谷歌的反机器人检测，提高搜索成功率
MCP服务器
- 使用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助手集成
反机器人保护
该项目实施了多层反机器人保护：
客户端级保护
- 具有随机延迟的请求间隔控制
- 工具调用超时保护
- 智能错误处理
服务器级保护
- 请求频率限制
- 请求之间的随机延迟
- 全球请求计数和管理
搜索级别保护
- 浏览器指纹随机化
- 设备和区域随机化
- 浏览器状态管理
- 自动验证码检测和处理
演出
- 响应时间：通常为5-15秒
- 成功率：95%以上（含州文件）
- 并发：支持异步操作
- 内存使用：优化了每次通话后的清理
- 稳定性：强大的错误恢复和超时处理