内容
<!-- mcp-name: io.github.VelvetSP/web-retrieval-mcp -->
# web-retrieval-mcp — web-retrieval-mcp 是一款开放源代码的 MCP 服务器，为 AI 代理提供两种网页工具 — 神经网络搜索（Exa）和分层网页抓取（Exa → 可选本地浏览器 → Firecrawl）— 作为内置 WebSearch/WebFetch 的替代品。 它保留了每个来源的出处，防止 SSRF，跨平台运行（macOS/Linux/Windows），并与 **Claude Code、Claude Desktop、Cursor 和任何 MCP 客户端** 兼容。 **在免费 API 层上运行。**
[](https://pypi.org/project/web-retrieval-mcp/)
[](./LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](#cross-platform-api-keys)
---
## 为什么要替换内置的网页工具？
代理的默认 `WebSearch` / `WebFetch` 往往会将许多来源合并成一个模糊的摘要，丢失出处，并且在 JavaScript 密集或反机器人页面上静默失败。 该服务器解决了这些问题：
| | 内置网页工具 | **web-retrieval-mcp** |
|---|---|---|
| **搜索结果** | 合并摘要，来源混淆 | **每个结果一个区块** — 每个结果保留其标题、网址、亮点和文本，加上 `来源` 尾部 |
| **抓取可靠性** | 单次尝试，放弃困难页面 | **分层备用**：Exa 内容 → 可选本地浏览器 → Firecrawl，带有 `[served by: …]` 出处头 |
| **JavaScript / 反机器人页面** | 通常失败 | 按需选择真正的无头浏览器（[camoufox](https://github.com/daijro/camoufox)） |
| **安全性** | — | **SSRF 防护** 在任何请求之前拒绝环回 / 私有 / 链路本地 / 多播主机 |
| **成本** | 捆绑 / 按模型供应商计量 | **免费** 在 Exa + Firecrawl 免费层（见下文） |
## 在免费 API 层上运行 — 而免费层已经足够
两个提供商都有一个真正可用的 **免费，不需要信用卡** 层，而且由于抓取首先命中 **Exa** （Firecrawl 仅作为备用），单个开发人员或代理很少触及 Firecrawl 配额：
| 提供商 | 免费层（验证 2026） | 在此服务器中的角色 |
|---|---|---|
| **Exa** | **1,000 请求 / 月**，不需要信用卡 | 支持 `web_search` **和** 首次 `web_fetch` 层 |
| **Firecrawl** | **1,000 页面 / 月**，不需要信用卡 | 仅备用抓取层 — 很少达到 |
| **camoufox** （本地浏览器） | **无限且免费** — 在您的机器上运行 | 按需 `render="always"` 层，用于 JavaScript/反机器人页面 |
对于每天大约 33 次搜索 **和** 33 次困难页面抓取的个人代理，无限期，**每月 0 美元**。 重量级生产工作负载可以独立升级任一提供商 — 分层和代码不会改变。
## 功能
- 🔎 **`web_search`** — 通过 Exa 进行神经网络 / 关键词 / 自动搜索，每个结果一个出处保留区块。
- 🌐 **`web_fetch`** — 通过具有出处头的弹性层链获取单个 URL 的可读内容。
- 🧱 **分层备用** — Exa 内容 → （可选）本地 camoufox 浏览器 → Firecrawl，因此困难页面仍然可以解析。
- 🛡️ **SSRF 防护** — 非公共主机（环回，RFC-1918，链路本地，多播，NAT64）在请求之前被拒绝。
- 🔑 **跨平台密钥** — 环境变量，密钥文件，`keyring` 库或操作系统密钥工具。 命令行上没有密钥。
- 🚫 **禁用内置工具的钩子** — 捆绑的 PreToolUse 钩子和一键安装程序，以便代理 **必须** 使用这些工具。
- 📦 **一键安装** — `uvx`，`pipx` 或 `pip`； 提供了两个控制台脚本。
## 快速入门
```bash
# 无需安装 — uvx 按需获取并运行：
uvx web-retrieval-mcp
# 或安装 CLI（隔离，推荐）：
pipx install web-retrieval-mcp # 或：pip install web-retrieval-mcp
# 可选附加组件：
pip install "web-retrieval-mcp[render]" # 本地无头浏览器层（render="always"）
pip install "web-retrieval-mcp[keyring]" # 跨平台原生密钥存储
python -m camoufox fetch # 一次性浏览器下载（仅当您使用 [render] 时）
```
> 在 [PyPI](https://pypi.org/project/web-retrieval-mcp/) 上。 喜欢最新的版本？ 从源代码安装：`pipx install git+https://github.com/VelvetSP/web-retrieval-mcp`。
获取免费 API 密钥：**Exa** → https://exa.ai · **Firecrawl** → https://firecrawl.dev — 然后：
```bash
export EXA_API_KEY="exa-..."
export FIRECRAWL_API_KEY="fc-..."
```
### 注册 Claude Code
```bash
# 在 `pipx install web-retrieval-mcp` 将脚本放入您的 PATH 之后：
claude mcp add web-retrieval -- web-retrieval-mcp
# 或无需事先安装，通过 uvx：
claude mcp add web-retrieval -- uvx web-retrieval-mcp
```
### 注册 Claude Desktop / 任意 MCP 客户端
```json
{
"mcpServers": {
"web-retrieval": {
"command": "web-retrieval-mcp",
"env": {
"EXA_API_KEY": "exa-...",
"FIRECRAWL_API_KEY": "fc-..."
}
}
}
}
```
`command` 上面假设 `web-retrieval-mcp` 位于 PATH（在 `pipx install` 之后）。 否则将 `command` 设置为 `uvx`，参数为 `args: ["--from", "git+https://github.com/VelvetSP/web-retrieval-mcp", "web-retrieval-mcp"]`。
## 工具
| 工具 | 签名 | 返回内容 |
|---|---|---|
| **`web_search`** | `web_search(query, num_results=8, mode="auto")` | 通过 Exa 进行神经网络搜索。 每个结果一个区块 — 每个结果都有自己的标题、网址、发布时间、亮点和文本 — 加上 `来源` 列表。 `mode` ∈ `auto` \| `neural` \| `keyword`。 |
| **`web_fetch`** | `web_fetch(url, render="auto", max_chars=20000, max_age_hours=None)` | 通过层链获取单个 URL 的可读内容，带有 `[served by: …]` 出处头。 |
### `web_fetch` 详细信息
通过层链获取单个 URL 的可读内容，返回带有 `[served by: …]` 头。
```
render="auto" （默认）→ Exa /contents → Firecrawl # 无本地浏览器
render="never" → Exa /contents → Firecrawl # 相同，显式
render="always" → camoufox （本地浏览器）→ Firecrawl # 用于 JavaScript / 反机器人页面
```
`max_age_hours` 控制 Exa 的新鲜度窗口（`0` = 强制新鲜；`None` = Exa 默认缓存）。
## 跨平台 API 密钥
密钥在进程内解析（从不通过命令行，命令行通过 `ps` 可见），最便宜/最安全的来源优先 — **在 macOS、Linux 和 Windows 上使用相同的代码路径**：
1. **环境变量** — `EXA_API_KEY`，`FIRECRAWL_API_KEY`。 普遍； **对无头 / CI 必需**。
2. **密钥文件** — dotenv 样式的 `KEY=value` 文件位于 `$WEB_RETRIEVAL_MCP_ENV_FILE` 或 `<config-dir>/keys.env`
（Linux/macOS 上为 `~/.config/web-retrieval-mcp/`，Windows 上为 `%APPDATA%\web-retrieval-mcp\`）。
3. **`keyring` 库** — 每个操作系统上的原生存储：macOS Keychain，Windows Credential Locker，Linux Secret Service / KWallet。 安装 `[keyring]` 附加组件，然后在服务 `web-retrieval-mcp` 下存储：
```bash
keyring set web-retrieval-mcp EXA_API_KEY
keyring set web-retrieval-mcp FIRECRAWL_API_KEY
```
4. **操作系统原生密钥 CLI** — macOS `security`，Linux `secret-tool`（libsecret），如果存在。
未扩展的 `${...}` 配置字面量被视为不存在。
## 阻止内置网页工具（Claude Code）
为了防止代理和子代理静默回落到保真度较低的内置工具，此存储库提供了一个 PreToolUse 钩子，**拒绝** `WebSearch` / `WebFetch` 并指向此处。 可靠地安装：
```bash
web-retrieval-mcp-install # 补丁 ~/.claude/settings.json（首先备份）
web-retrieval-mcp-install --print # 仅预览，不写入任何内容
web-retrieval-mcp-install --register-mcp # 还运行 `claude mcp add`
web-retrieval-mcp-install --uninstall # 删除钩子
```
突破口：`touch ~/.claude/.web-builtins-allow` 重新启用内置工具以供会话使用； 删除文件以重新启用。 钩子是纯 POSIX `sh`（无 `jq`）。
## 安全 — SSRF
`web_fetch` 在任何请求之前验证每个 URL：非 `http(s)` 方案和解析为非公共 IP 的任何主机（环回，私有/RFC-1918，链路本地，保留/NAT64，多播）都被拒绝。 唯一在您的机器上运行真正的浏览器的层（camoufox）是 **按需**（`render="always"`），因此默认路径永远不会暴露它。 剩余部分：camoufox 层遵循重定向，因此前置检查仅涵盖初始 URL — 完整的闭包需要一个验证转发代理。 默认的 `auto`/`never` 路径永远不会运行浏览器。
## 常见问题
**什么是 web-retrieval-mcp？**
一个开源的 MCP（模型上下文协议）服务器，为 AI 代理提供两种网页工具 — `web_search`（Exa）和 `web_fetch`（Exa → 本地浏览器 → Firecrawl）— 作为内置网页访问的替代品，保留出处并具有 SSRF 防护。
**它与 Claude Code 兼容吗？**
是的。 使用 `claude mcp add web-retrieval -- web-retrieval-mcp` 注册，并可选地安装捆绑的钩子，以便在这些工具的 favor 中禁用内置的 `WebSearch`/`WebFetch`。
**它是免费的吗？**
是的。 代码是 MIT 许可的，它在 Exa（1,000 请求/月）和 Firecrawl（1,000 页面/月）的免费层上运行，这两个都不需要信用卡。 本地浏览器层是免费且无限的。
**支持哪些平台？**
macOS、Linux 和 Windows。 密钥解析和服务器是跨平台的； 本地浏览器层需要可选的 `[render]` 附加组件。
**它比内置的 WebSearch/WebFetch 更好吗？**
它返回每个来源的一个结果区块（无合并摘要），保留出处，通过多个抓取后端备用，因此困难/JavaScript 页面仍然可以解析，并防止 SSRF。
**我需要浏览器堆栈吗？**
不需要。 搜索和默认抓取路径只需要 `mcp` + `anyio`。 camoufox/playwright 浏览器是可选的 `[render]` 附加组件，仅用于 `render="always"`。
## 发布
> **状态：** ✅ 在 [PyPI](https://pypi.org/project/web-retrieval-mcp/) 上 · ✅ [GitHub Release](https://github.com/VelvetSP/web-retrieval-mcp/releases) · ✅ 在 [官方 MCP 注册表](https://registry.modelcontextprotocol.io/v0/servers?search=web-retrieval) 中列出为 `io.github.VelvetSP/web-retrieval-mcp`。
聚合器（PulseMCP、Glama、mcp.so、Smithery）从官方注册表中摄取，因此该列表会自动传播到它们。 [`server.json`](./server.json) 清单和完整的操作手册位于 [`PUBLISHING.md`](./PUBLISHING.md) 中。 对于新版本：增加版本，`python -m build`，`twine upload`，然后 `mcp-publisher publish`。
## 贡献
问题和 PR 欢迎在 https://github.com/VelvetSP/web-retrieval-mcp。 服务器是一个模块（`src/web_retrieval_mcp/server.py`）；`stdout` 仅为 JSON-RPC — 在 `stderr` 上保留所有诊断信息。
## 许可证
[MIT](./LICENSE) © VelvetSP
<sub>关键词：MCP 服务器，模型上下文协议，AI 代理网页搜索，LLM 网页抓取，Exa API，Firecrawl API，camoufox，Claude Code MCP，网页抓取代理，RAG 检索，SSRF 安全抓取，跨平台，免费网页搜索 API。</sub>
