内容
# mcp-web-tools
MCP 服务器提供用于 AI 助手的网页搜索和内容提取工具。**开箱即用，无需配置** — 无需 API 密钥，无需 Docker。搜索和提取后端是解耦的，可以在 [SearXNG](https://searxng.org) （公共或自托管）、[Tavily](https://tavily.com) （托管）和 [Firecrawl](https://firecrawl.dev) （无密钥或自托管）之间单独更换。
## 安装
无需 API 密钥，无需 Docker，无需配置文件。只需添加服务器 — 它开箱即用，使用公共 SearXNG 实例进行搜索，使用 Firecrawl 无密钥进行提取。
**Claude Code（命令行）：**
```bash
claude mcp add mcp-web-tools -- npx -y mcp-web-tools
```
**Claude Desktop** — 添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"mcp-web-tools": {
"command": "npx",
"args": ["-y", "mcp-web-tools"]
}
}
}
```
**OpenCode** — 添加到 `~/.config/opencode/opencode.json`（全局）或项目根目录下的 `.opencode.json`：
```jsonc
"mcp-web-tools": {
"type": "local",
"command": ["npx", "-y", "mcp-web-tools"]
}
```
就这样 — 搜索和提取都无需配置即可使用。下面章节介绍如何自定义后端。
## 工作原理
服务器有两个独立的后端，每个后端都可以通过客户端配置中的环境变量进行覆盖：
- **搜索** (`WEBTOOLS_SEARCH_PROVIDER`)：默认为 `searxng` — 使用公共 SearXNG 实例。覆盖为 `tavily`，或将 `SEARXNG_URL` 指向自己的实例。
- **提取** (`WEBTOOLS_EXTRACT_PROVIDER`)：默认为 `firecrawl` 无密钥 — 无需 API 密钥。覆盖为 `tavily`，或设置为 `none` 以禁用 `web_read`。
> ⚠️ 默认公共 SearXNG 实例由志愿者运营。如果实例宕机或速率限制已达上限，请将 `SEARXNG_URL` 设置为其他实例或 [运行自己的实例](#self-hosting-searxng-optional)。
## 自定义后端
### 使用不同的 SearXNG 实例
将 `SEARXNG_URL` 指向任何 SearXNG 实例 — 公共、自托管或团队共享：
```bash
claude mcp add mcp-web-tools -e SEARXNG_URL=https://your-instance.example -- npx -y mcp-web-tools
```
在 [searx.space](https://searx.space/) 上查找公共实例。
### 使用 Tavily 代替（单个密钥，两个工具）
```bash
claude mcp add mcp-web-tools -e WEBTOOLS_SEARCH_PROVIDER=tavily -e TAVILY_API_KEY=your-key -- npx -y mcp-web-tools
```
在 [tavily.com](https://tavily.com) 获取密钥。提取自动使用 Tavily（密钥重复使用）。
### Firecrawl 选项
默认的 Firecrawl 无密钥层提供约 1000 次提取/月。要提高限制：
```bash
claude mcp add mcp-web-tools -e FIRECRAWL_API_KEY=fc-your-key -- npx -y mcp-web-tools
```
### 提供者组合
| 搜索 | 提取 | 环境变量 |
|---|---|---|
| SearXNG（默认） | Firecrawl 无密钥（默认） | *无* |
| SearXNG | Firecrawl 有密钥 | `FIRECRAWL_API_KEY` |
| SearXNG | Tavily | `WEBTOOLS_EXTRACT_PROVIDER=tavily` + `TAVILY_API_KEY` |
| SearXNG | 无（禁用 `web_read`） | `WEBTOOLS_EXTRACT_PROVIDER=none` |
| Tavily | Tavily | `WEBTOOLS_SEARCH_PROVIDER=tavily` + `TAVILY_API_KEY` |
更多 `claude mcp add` 一行命令：
```bash
# 指向自己的 SearXNG
claude mcp add mcp-web-tools -e SEARXNG_URL=http://localhost:8080 -- npx -y mcp-web-tools
# SearXNG 搜索 + Tavily 提取
claude mcp add mcp-web-tools -e WEBTOOLS_EXTRACT_PROVIDER=tavily -e TAVILY_API_KEY=your-key -- npx -y mcp-web-tools
# 仅搜索，禁用 web_read
claude mcp add mcp-web-tools -e WEBTOOLS_EXTRACT_PROVIDER=none -- npx -y mcp-web-tools
# Firecrawl 有密钥（更高限制）
claude mcp add mcp-web-tools -e FIRECRAWL_API_KEY=fc-your-key -- npx -y mcp-web-tools
```
## 自托管 SearXNG（可选）
为了完全控制可用性和速率限制，请运行自己的 SearXNG 实例并将 `SEARXNG_URL` 指向它。
关键要求：SearXNG 必须启用 **JSON 输出**。默认 Docker 镜像仅提供 HTML 服务，因此您需要一个包含 `json` 的 `search.formats` 的 `settings.yml` 文件。请参阅官方文档：
→ [SearXNG — 安装和 Docker](https://docs.searxng.org/admin/installation-docker.html)
→ [SearXNG — settings.yml 参考](https://docs.searxng.org/admin/settings/settings.html)
最小 `settings.yml`（挂载到容器中）：
```yaml
use_default_settings: true
server:
secret_key: "your-random-secret"
search:
formats: [html, json]
```
然后将服务器指向它：
```bash
claude mcp add mcp-web-tools -e SEARXNG_URL=http://localhost:8080 -- npx -y mcp-web-tools
```
## 完全自托管（可选）
在您的机器上运行所有内容，无需外部网络调用：SearXNG 用于搜索，Firecrawl 用于提取，均在您的机器上。
**1. SearXNG** — 请参阅上面的 [自托管 SearXNG](#self-hosting-searxng-optional)。
**2. Firecrawl** — 使用 Firecrawl 的官方自托管指南。他们的堆栈需要 Postgres、RabbitMQ、Redis 和 Playwright：
→ [firecrawl/firecrawl — SELF_HOST.md](https://github.com/firecrawl/firecrawl/blob/main/SELF_HOST.md)
**3. 将 mcp-web-tools 指向两者：**
```bash
claude mcp add mcp-web-tools -e SEARXNG_URL=http://localhost:8080 -e FIRECRAWL_URL=http://localhost:3002 -- npx -y mcp-web-tools
```
## 工具
### `web_search`
搜索网页。返回结果，包括标题、URL 和摘要。后端在服务器端配置（Tavily 或 SearXNG）。
**参数：**
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `query` | 字符串 | *必填* | 搜索查询 |
| `maxResults` | 数字 | 5 | 最大结果数（1-20） |
| `searchDepth` | 字符串 | `"basic"` | `"basic"`、`"fast"`、`"ultra-fast"`（1 积分）或 `"advanced"`（2 积分） |
| `topic` | 字符串 | `"general"` | `"general"`、`"news"` 或 `"finance"` |
| `timeRange` | 字符串 | — | `"day"`、`"week"`、`"month"` 或 `"year"` |
| `startDate` | 字符串 | — | 开始日期筛选器（`YYYY-MM-DD`） |
| `endDate` | 字符串 | — | 结束日期筛选器（`YYYY-MM-DD`） |
| `includeDomains` | 字符串[] | — | 仅包含来自这些域的结果 |
| `excludeDomains` | 字符串[] | — | 排除来自这些域的结果 |
| `includeAnswer` | 布尔值 | `true` | 包括 AI 生成的答案摘要 |
### `web_read`
从网页中提取干净的内容。返回网页文本，去除导航、广告和脚本。支持每个请求最多 20 个 URL。后端在服务器端配置（Tavily 或 Firecrawl）。当 `WEBTOOLS_EXTRACT_PROVIDER=none` 时不注册。
**参数：**
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `urls` | 字符串[] | *必填* | 从中提取内容的 URL（1-20）。必须是 `http://` 或 `https://` |
| `extractDepth` | 字符串 | — | `"basic"`（每 5 个 URL 1 积分，原始页面 HTML 作为 Markdown，包括导航/样板）或 `"advanced"`（每 5 个 URL 2 积分，干净的文章内容，去除导航/广告/侧边栏/页脚） |
| `includeImages` | 布尔值 | `false` | 包括提取的图像 URL |
### `credit_balance`
检查提供者的信用余额和使用情况。当活动提供者没有信用系统时，返回“不支持”（例如 SearXNG）。
## GitHub 工具
三个用于直接通过 GitHub REST API 读取公共 GitHub 仓库内容的工具。这些工具不通过搜索提供者 — 它们存在于自己的命名空间中，并匿名工作。
### `github_get_repo_structure`
列出 GitHub 仓库路径的目录结构（单级，非递归）。有助于了解项目布局。
**参数：**
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `repo` | 字符串 | *必填* | 仓库，格式为 `owner/repo`（例如 `vitejs/vite`） |
| `path` | 字符串 | `/` | 仓库内的目录路径 |
| `ref` | 字符串 | 默认分支 | Git 引用（分支、标签或提交 SHA） |
### `github_read_file`
读取 GitHub 仓库中文件的完整内容。大于 512 KB 或检测为二进制的文件将被拒绝。
**参数：**
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `repo` | 字符串 | *必填* | 仓库，格式为 `owner/repo` |
| `path` | 字符串 | *必填* | 仓库内文件路径 |
| `ref` | 字符串 | 默认分支 | Git 引用（分支、标签或提交 SHA） |
### `github_search_repo`
在单个调用中搜索 GitHub 仓库的代码、问题和拉取请求。当 `kind=all`（默认）时，所有三个搜索并行运行，结果按类型分组。代码搜索使用 GitHub 的 `/search/code` 端点，**需要 `GITHUB_TOKEN`**（匿名代码搜索不受 GitHub 支持 — 如果没有令牌，调用将返回 401）。
**参数：**
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `repo` | 字符串 | *必填* | 仓库，格式为 `owner/repo` |
| `query` | 字符串 | *必填* | 搜索查询。支持 GitHub 搜索语法（例如 `"auth token"`、`"bug in login"`、`"label:bug"`） |
| `kind` | 字符串 | `"all"` | `"code"`、`"issues"`、`"prs"` 或 `"all"`（扩展到所有三个并行） |
| `state` | 字符串 | `"all"` | 仅过滤问题/拉取请求（`"open"`、`"closed"` 或 `"all"`）。代码搜索忽略此参数 |
| `maxResults` | 数字 | `5` | 每个类型的最大结果数（1-10）。当 `kind=all` 时，工具返回最多 3 倍此数字的结果 |
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `WEBTOOLS_SEARCH_PROVIDER` | 否 | `searxng` | 搜索后端：`tavily` 或 `searxng` |
| `SEARXNG_URL` | 否 | `https://search.mdosch.de` | SearXNG 实例的基本 URL。默认为公共实例；设置为自己的实例以提高可靠性 |
| `TAVILY_API_KEY` | 条件 | — | Tavily API 密钥。在搜索或提取提供者为 `tavily` 时需要。在 [tavily.com](https://tavily.com) 获取 |
| `WEBTOOLS_EXTRACT_PROVIDER` | 否 | 派生\* | 提取后端：`tavily`、`firecrawl` 或 `none`。当未设置时：如果搜索是 tavily，则默认为 `tavily`，否则默认为 `firecrawl` |
| `FIRECRAWL_URL` | 否 | `https://api.firecrawl.dev` | Firecrawl 实例的基本 URL。接受任何 HTTP(S) URL（本地、托管或自托管） |
| `FIRECRAWL_API_KEY` | 否 | — | 可选。省略无密钥模式（~1000 积分/月，IP 分桶）。设置为更高的托管限制。托管模式下忽略 |
| `GITHUB_TOKEN` | 否 | — | `github_*` 工具的 GitHub 令牌。提高速率限制从 60 到 5000 请求/小时。在 [github.com/settings/tokens](https://github.com/settings/tokens) 创建（公共仓库不需要范围） |
| `WEBTOOLS_MAX_RESULTS` | 否 | `5` | 默认结果数（必须为 1-20） |
| `WEBTOOLS_SEARCH_DEPTH` | 否 | `basic` | 默认搜索深度 |
| `WEBTOOLS_CACHE_TTL` | 否 | `3600` | 缓存 TTL（秒）（0 禁用） |
| `WEBTOOLS_CACHE_MAX_ENTRIES` | 否 | `100` | 缓存条目最大数量（0 禁用缓存） |
| `WEBTOOLS_CACHE_SWEEP_INTERVAL_MS` | 否 | `300000` | 清除过期条目的间隔（毫秒）（0 禁用周期性清除） |
| `WEBTOOLS_DEBUG` | 否 | — | 设置为任意值以启用 stderr 调试日志 |
\* `WEBTOOLS_EXTRACT_PROVIDER` 在 `WEBTOOLS_SEARCH_PROVIDER=tavily` 时默认为 `tavily`，否则默认为 `firecrawl`。
## 提供者限制
每个后端支持的功能子集不同。不支持的参数将被静默忽略。
| 功能 | Tavily | SearXNG | Firecrawl |
|---|---|---|---|
| `web_search` | ✅ | ✅ | —（仅提取） |
| `web_read` / 提取 | ✅ | —（仅搜索） | ✅ |
| AI 答案（`includeAnswer`） | ✅ | ❌ 忽略 | — |
| 原生域名过滤器 | ✅ | 后过滤（可能会返回的结果较少） | — |
| `topic=finance` | ✅ | 映射到 `general` | — |
| `searchDepth` | ✅ | ❌ 忽略 | — |
| `extractDepth=advanced` | ✅ | — | ✅（映射到 `onlyMainContent`） |
| `includeImages` | ✅ | — | ❌ 忽略 |
| 信用/使用情况（`credit_balance`） | ✅ | ❌ "不支持" | ❌ "不支持" |
**常见陷阱：**
- **SearXNG 403** — JSON 输出在实例上被禁用。编辑 `settings.yml`（`search.formats` 必须包括 `json`）并重启。[后端](#searxng-search-default) 中的 `docker run` 代码段在此基础上进行了设置文件。
- **SearXNG 429** — 速率限制器已开启。在 `settings.yml` 中禁用 `server.limiter`，或使用不同的实例。
- **Firecrawl 429** — 无密钥免费层耗尽（~1000 积分/月，10/分钟）。设置 `FIRECRAWL_API_KEY` 以获得更高的限制，或自托管。
## 示例输出
```
Node.js 22 introduces require() support for ES modules, a WebSocket client, and updates to the V8 JavaScript engine.
### 1. [Node.js — Node.js 22 is now available!](https://nodejs.org/blog/announcements/v22-release-announce)
> We're excited to announce the release of Node.js 22! Highlights include require()ing ES modules, a WebSocket client, updates of the V8 JavaScript engine, and more!
*响应时间：1.2s*
---
来源：
- [Node.js — Node.js 22 is now available!](https://nodejs.org/blog/announcements/v22-release-announce)
```
## 安全说明
此服务器设计用于受信任的 AI 客户端（Claude Code、Claude Desktop、OpenCode）。`web_read` 工具接受调用客户端提供的任何 `http(s)://` URL，不实现 SSRF 保护（例如阻止私有/内部 IP 范围）。不要将此服务器暴露给不受信任的输入。
## 许可证
MIT
