heventure-search-mcp

一个无需 API Key 即可使用的网页搜索 MCP（Model Context Protocol）服务，支持多搜索引擎并发与自动回退。

🔗 基于上游项目：HughesCuit/heventure-search-mcp v1.5.3

本仓库在上游基础上增加了 Google CSE 引擎支持（参考 SearXNG 的 google_cse.py 引擎实现），以及 Bing 中文搜索语言检测修复等改进。感谢原作者 HughesCuit 和 SearXNG 项目的工作。

✨ 特性

• 多引擎并发：DuckDuckGo + Bing + Google + SerpAPI + Google CSE，一次查询覆盖多个搜索引擎

• 零配置可用：不配任何 API Key 即可使用 DuckDuckGo + Bing + Google（HTML 解析）

• 按需启用：配置 SERPAPI_KEY / TAVILY_API_KEY / GOOGLE_CSE_ID 后自动激活对应引擎

• 智能缓存：内置 LRU 缓存，减少重复请求

• 自动重试：网络超时自动重试，提高稳定性

• SSRF 防护：内置 URL 安全校验

Related MCP server: Multi-Search MCP Server

🔍 支持的搜索引擎

📦 安装

# 克隆项目
git clone https://github.com/yourname/heventure-search-mcp.git
cd heventure-search-mcp

# 安装依赖
pip install -r requirements.txt

⚙️ 配置

所有配置通过环境变量传入，无需修改代码：

# 必需（无则仅用免费引擎）
export SERPAPI_KEY="your_serpapi_key"        # https://serpapi.com
export GOOGLE_CSE_ID="your_cse_id"           # https://programmablesearchengine.google.com
export TAVILY_API_KEY="your_tavily_key"      # https://tavily.com

# 可选
export WEB_SEARCH_SSL_VERIFY="true"          # SSL 验证（默认 true）
export SOCKS_PROXY="socks5://127.0.0.1:1080"  # SOCKS5 代理

🚀 使用

作为 MCP Server 运行

python -m heventure_search_mcp.server

在 QwenPaw 中配置

在 drivers/mcp/heventure-search.yaml 中：

name: heventure-search
type: stdio
command: /path/to/python3
args:
  - -m
  - heventure_search_mcp.server
env:
  PYTHONPATH: /path/to/heventure_search_mcp
  SERPAPI_KEY: your_serpapi_key
  GOOGLE_CSE_ID: your_cse_id

搜索引擎选择

通过 search_engine 参数指定引擎：

📖 API

web_search

搜索网页，返回标题、URL、摘要。

参数：

• query（必需）：搜索查询字符串

• search_engine（可选）：搜索引擎，默认 both

• max_results（可选）：最大结果数，默认 10，最大 20

get_webpage_content

获取指定网页的文本内容。

参数：

• url（必需）：要获取内容的网页 URL

📄 License

MIT

🙏 Acknowledgements

• 原始项目：heventure-search-mcp by HughesCuit

• Google CSE 引擎实现参考：SearXNG — searx/engines/google_cse.py

🏗️ 开发环境

本项目在以下环境中开发与测试：

• Agent 框架：QwenPaw（by AgentScope team from Qwen lab）

• 运行环境：Alibaba Cloud（新加坡节点），Linux 容器

• Python：3.11

• 部署方式：作为 QwenPaw MCP 工具（stdio 模式），由 supervisor 托管