内容
# 🔍 网页搜索增强版 - MCP 服务器
<p align="center">
<img src="docs/assets/web-search-plus-logo.png" alt="网页搜索增强版 logo" width="180">
</p>
[](https://pypi.org/project/web-search-plus-mcp/)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](./LICENSE)
[](https://glama.ai/mcp/servers/robbyczgw-cla/web-search-plus-mcp)
**适用于 MCP 客户端的多提供商网页搜索和并行 URL 提取。**
`web-search-plus-mcp` 是 Web Search Plus 的独立 MCP 包装。它为 Claude Desktop、Cursor、NanoBot、Hermes 原生 MCP 以及其他 MCP 兼容主机提供与 Hermes/OpenClaw Web Search Plus 工具相同的提供商家族。
版本说明：`web-search-plus-mcp` 使用其自己的 MCP 包版本（`0.16.0`），同时在适用情况下跟踪 Web Search Plus v2.8.1 引擎家族。插件包版本为 `hermes-web-search-plus v2.8.x`；Hermes 独有设置/快速通道命令未由 MCP 服务器公开。
## ✨ 功能
- **14 个搜索提供商 + 自动路由** — 提供商元数据、模式、默认值和受保护/自动行为从共享的 Web Search Plus 提供商注册表中生成
- **7 个提取提供商，具有私有目标保护** — Tavily、Exa、Linkup、Parallel、Firecrawl、You.com、Keenable、Serper
- **路由 v2.3 自动路由** — 基于注册表的多语言/当前、文档/API、arXiv、CVE/安全、本地/购物、开源发现和答案/合成查询的路由
- **质量报告 + 医生检查** — 可选的路由/结果诊断以及针对配置的提供商/缓存的紧凑离线健康检查
- **研究模式** — 选择加入多提供商搜索 + 顶级来源提取，带有时间预算
- **引导 CLI** — `status`、`list`、`setup` 和持久路由 `config` 助手，用于 MCP 环境/配置连接
- **零安装运行** — `uvx web-search-plus-mcp`
- **MCP 原生** — 暴露稳定的 `web_search` 和 `web_extract` 工具的标准输入/输出服务器
## 🚀 快速开始
```bash
# 使用 uvx 立即运行 MCP 服务器
uvx web-search-plus-mcp
# 或全局安装
pip install web-search-plus-mcp
web-search-plus-mcp
```
至少需要一个提供商凭证才能进行搜索。提取需要至少一个具有提取能力的提供商密钥。
## 🧭 更简单的引导
检查配置的提供商：
```bash
web-search-plus-mcp status
```
列出提供商或预设：
```bash
web-search-plus-mcp list providers
web-search-plus-mcp list presets
```
编写一个入门 `.env` 模板，并打印一个规范的 MCP 标准输入/输出代码段：
```bash
web-search-plus-mcp setup --preset starter
```
推荐的入门预设是 **You.com + Serper + Linkup**。它为快速当前搜索、Google 式发现和提取工作流程提供了实用的路由 v2 基线，而无需在第一天连接所有提供商。
`status` 在未配置搜索提供商时返回非零退出代码，这使其在脚本中可用作配置检查。
持久路由偏好存储在 `config.json` 中，而不是 `.env` 中：
```bash
web-search-plus-mcp config show
web-search-plus-mcp config set-default you # 严格的固定提供商模式
web-search-plus-mcp config set-routing on # 恢复路由 v2 自动路由
web-search-plus-mcp config set-priority you,serper,exa,firecrawl,tavily,linkup,parallel,brave,keenable
web-search-plus-mcp config set-fallback serper
web-search-plus-mcp config disable perplexity
web-search-plus-mcp config enable perplexity
web-search-plus-mcp config disable kilo-perplexity
web-search-plus-mcp config set-threshold 0.45
web-search-plus-mcp config reset --yes
```
对于隔离的 MCP 主机安装，请使用 `--config-path /path/to/config.json` 或 `WEB_SEARCH_PLUS_CONFIG=/path/to/config.json`。提供商密钥存储在环境变量中；路由行为存储在 `config.json` 中。
其他预设：
- `minimal` — 仅 You.com
- `lean` — You.com + Linkup
- `starter` — You.com + Serper + Linkup
- `all` — 每个受支持的提供商环境变量
## ⚙️ MCP 主机配置
适用于 Claude Desktop、Cursor、NanoBot 或 Hermes 原生 MCP 的规范标准输入/输出代码段：
```json
{
"mcpServers": {
"web-search-plus": {
"command": "uvx",
"args": ["web-search-plus-mcp"],
"env": {
"YOU_API_KEY": "your_you_key",
"SERPER_API_KEY": "your_serper_key",
"LINKUP_API_KEY": "your_linkup_key"
}
}
}
}
```
常见的粘贴位置：
- Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
- Claude Desktop Linux: `~/.config/Claude/claude_desktop_config.json`
- Cursor: 项目/用户 MCP 配置，使用相同的 `mcpServers` 形状
- Hermes 原生 MCP: `~/.hermes/config.yaml` 下的 `mcp_servers`，具有等效的命令/环境字段
您也可以在包/项目旁边放置一个 `.env` 文件，其中包含相同的变量。
## 🔎 搜索提供商
- **You.com** — 当前、多语言和答案形快照的快速路由 v2 核心提供商
- **Serper** — Google 式事实、新闻、购物、本地查询
- **Exa** — 语义发现、GitHub/文档、arXiv/学术和开源发现
- **Firecrawl** — 网页搜索加刮取内容
- **Parallel** — 显式仅限 LLM 就绪的网页搜索，带有长摘录（`PARALLEL_API_KEY`，`auto_allow=false`）
- **Tavily** — 研究和分析
- **Linkup** — 源代码支持的接地/引用
- **Brave** — 显式仅限独立网页索引，默认情况下（`BRAVE_API_KEY`，`auto_allow=false`）
- **Perplexity** — 显式仅限 Perplexity API 合成答案（`PERPLEXITY_API_KEY`，`sonar-pro`，`auto_allow=false`）
- **Kilo Perplexity** — 通过 Kilo 网关的显式仅限 Perplexity（`KILOCODE_API_KEY`，`perplexity/sonar-pro`，`auto_allow=false`）
- **SearXNG** — 隐私优先的自托管元搜索
- **SerpBase** — 显式仅限 Google SERP API（`SERPBASE_API_KEY`，`auto_allow=false`）
- **Querit** — 显式仅限多语言、实时 AI 搜索（`QUERIT_API_KEY`，`auto_allow=false`）
- **Keenable** — 具有搜索和提取的独立网页索引（`KEENABLE_API_KEY`，或选择加入无密钥公共层；默认关闭）
## 📄 提取提供商
- **Tavily** — 默认首选；v2.1 基准测试中速度最快、可靠性最高的提取
- **Exa** — 快速内容 API，对于文档/学术页面有强大的支持
- **Linkup** — 干净的 Markdown 和源代码支持的获取
- **Parallel** — 快速富含摘录的文档备用，带有可选的全内容提取
- **Firecrawl** — 稳健的刮取备用，对于 JS 密集型/阻止的页面非常有用
- **You.com** — 可用的 LLM 就绪快照/内容
- **Keenable** — 最低优先级密钥或显式选择加入公共备用
### Keenable 无密钥公共访问
Keenable 通过 `KEENABLE_API_KEY` 暴露身份验证端点。它还具有无密钥 `/public` 端点，但这些端点**默认禁用**。如果没有密钥，Keenable 被视为未配置，除非您显式启用公共出口：
```json
{ "keenable": { "allow_public": true } }
```
或设置：
```bash
KEENABLE_ALLOW_PUBLIC=1
```
在私有或生产环境中使用 API 密钥。公共端点会将查询和获取的 URL 发送到共享的无身份验证服务，并保持最低优先级备用。
### 私有/内部提取目标保护
`web_extract` 在调用任何提供商之前会阻止指向私有或内部网络的用户提供目标 URL。这涵盖了环路、RFC1918、CGNAT/共享地址范围、IPv6 本地/映射私有范围、多播、云元数据主机和解析为私有/内部 IP 的主机名。
操作员配置的提供商端点是分开的；本地 Firecrawl 兼容后端仍然可以在 `127.0.0.1` 上运行，通过提供商配置。如果您有意需要提取受信任的内网 URL，请显式选择加入：
```json
{ "extract": { "allow_private_urls": true } }
```
对于公共/代理控制的 URL 提取，请关闭此选项。
### GroktoCrawl / 本地 Firecrawl 兼容后端
Firecrawl 提供商可以通过在 `config.json` 中覆盖其搜索和刮取 URL 来针对本地 Firecrawl-v2 兼容后端。例如，监听 `127.0.0.1:8080` 的本地 [GroktoCrawl](https://github.com/groktopus/groktocrawl) 实例可以在不添加单独提供商的情况下使用：
```json
{
"firecrawl": {
"api_url": "http://127.0.0.1:8080/v2/search",
"scrape_url": "http://127.0.0.1:8080/v2/scrape"
}
}
```
如果您的后端强制执行承载身份验证，请保留 `FIRECRAWL_API_KEY` 配置；本地开发实例可能会忽略该头部。这不会使 GroktoCrawl 成为默认提供商，也不会声称涵盖 Firecrawl 的每个端点。
## 🛠 MCP 工具参考
此 MCP 服务器暴露稳定的 `web_search` 和 `web_extract` 工具。旧版测试版 `web_answer` 工具已删除，以匹配 Web Search Plus v2.1+；使用 `web_search` 进行源发现，并在需要时让 MCP 主机从结果中合成。
Hermes 插件公开与 `web_search_plus` 和 `web_extract_plus` 相同的稳定功能；名称不同，因为 MCP 和 Hermes 使用不同的工具接口。
### `web_search`
用于源发现、当前事件、价格、天气、体育阵容、赛程等。
参数：
- `query` — 必需的搜索查询
- `provider` — `auto`、`serper`、`brave`、`tavily`、`exa`、`linkup`、`firecrawl`、`parallel`、`perplexity`、`kilo-perplexity`、`you`、`searxng`、`serpbase`、`querit`、`keenable`
- `count` — 返回结果数，默认为 `5`，最大 `20`
- `depth` — Exa 深度：`normal`、`deep`、`deep-reasoning`
- `time_range` — `hour`、`day`、`week`、`month`、`year`
- `include_domains` / `exclude_domains` — 域名允许/拒绝列表
- `mode` — `normal` 或 `research`
- `quality_report` — 包括路由/结果诊断
- `research_time_budget` — 研究模式的最佳努力时钟预算
MCP 参数示例：
```json
{
"query": "最新 AI 硬件新闻",
"provider": "auto",
"count": 5,
"quality_report": true
}
```
### `web_extract`
参数：
- `urls` — 必需的 URL 列表
- `provider` — `auto`、`tavily`、`exa`、`linkup`、`parallel`、`firecrawl`、`you`、`keenable`
- `format` — `markdown` 或 `html`
- `include_images` — 在支持时包含图像元数据
- `include_raw_html` — 在支持时包含原始 HTML
- `render_js` — 在支持时渲染 JavaScript
MCP 参数示例：
```json
{
"urls": ["https://example.com"],
"provider": "auto",
"format": "markdown"
}
```
## 🧠 路由 v2 示例
- `東京 AI ニュース 今日` → You.com 多语言/当前搜索
- `arXiv 2024 LLM scaling laws` → Exa 学术发现
- `CVE-2025 openssl advisory` → Serper 安全/当前搜索
- `best bookshelf speakers under 1000 EUR Austria` → Serper/Firecrawl 购物/本地搜索
- `open source alternatives to Linear` → Exa/Firecrawl 开源发现
- `summarize the tradeoffs of RAG vs fine-tuning` → You.com 带有合成提示元数据的
受保护的提供商仍然可以显式调用。要让一个参与 `provider="auto"`，请选择加入：
```bash
web-search-plus-mcp config set-auto-allow parallel on
web-search-plus-mcp config set-auto-allow parallel off
```
## 致谢
基于 Web Search Plus 路由引擎，包装为独立的 MCP 服务器。
## 许可证
MIT © 2026 robbyczgw-cla
