内容
# 简单网页搜索MCP
一个零配置的MCP服务器，允许任何LLM **搜索网页** 和 **读取网页内容**。无需API密钥，无需浏览器安装，无需配置文件 — 只需运行它。
```bash
npx simple-web-search-mcp --log
```
## 功能特点
- **两个工具**：`search_web`（搜索互联网）和`read_url`（读取任意网页）
- **9个搜索引擎** — 按可配置的顺序尝试搜索引擎，自动降级：DuckDuckGo、 Brave、 Bing、 Google、 Ecosia、 Startpage、 Qwant、 Yahoo、 Yandex
- **`/search` 和 `/read` 提示** — 在Claude Desktop和其他MCP客户端中工作的斜杠命令
- **速率限制** — 每个主机限制，自动重试 + 429/503错误时的指数退避
- **默认安全** — 输入验证、URL方案强制执行（仅http/https）、HTML剥离、控制字符删除、markdown注入转义、内容隔离
- **零配置** — 默认开箱即用，通过CLI标志、环境变量或配置文件完全可定制
- **可选文件日志** — 使用 `--log` 将每日日志文件写入 `~/.simple-web-search-mcp/logs/`
- **无需API密钥** — 所有搜索引擎都通过纯HTTP工作
- **无需浏览器安装** — 纯HTTP与Node.js内置 `fetch` + cheerio
- **干净的markdown输出** — 结构化结果，LLM可以实际使用
## 安装设置
### Cursor
添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"web-search": {
"command": "npx",
"args": ["-y", "simple-web-search-mcp", "--log"]
}
}
}
```
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"web-search": {
"command": "npx",
"args": ["-y", "simple-web-search-mcp", "--log"]
}
}
}
```
### 自定义选项
```json
{
"mcpServers": {
"web-search": {
"command": "npx",
"args": [
"-y", "simple-web-search-mcp",
"--log",
"--engines", "brave,duckduckgo",
"--max-results", "5"
]
}
}
}
```
## 工具
### `search_web`
搜索互联网并获取markdown格式的结果。按顺序尝试配置的搜索引擎，在失败时自动降级。您可以请求特定搜索引擎优先尝试。默认结果包括`[1]`、`[2]`等markdown链接在每个结果的标题和摘要旁边（链接到源URL），以及底部的**参考文献**部分；可以通过配置`citations: false`或 `--no-cite`禁用，或者通过 `--cite`强制启用。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `query` | 字符串 | 搜索查询 |
| `prefer_engine` | 字符串 | 可选。优先尝试的搜索引擎（例如 `duckduckgo`、`brave`、`bing`） |
| `include_citations` | 布尔值 | 可选。如果设置，则覆盖本次调用的服务器配置（包括/省略参考文献） |
| `think` | 布尔值 | 可选。如果为真，则查询多个搜索引擎，合并URL，并返回编译的研究（前3个搜索引擎） |
### `read_url`
获取网页内容并返回干净、易读的markdown格式。剥离导航、广告和模板。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `url` | 字符串 | 要获取的URL（例如 `https://...`） |
## 斜杠命令（提示）
支持提示的MCP客户端将显示这些 `/` 命令：
| 命令 | 描述 |
| --- | --- |
| `/search <input>` | 搜索网页。输入查询；可选地以标志结尾： `-engine`、`-cite`、`-no-cite`、`-think`（例如 `weather --brave`、`topic --think` 进行深入研究）。提示标志覆盖MCP/服务器配置。 |
| `/read <url>` | 读取网页并总结其内容 |
** `/search` 标志** — 在查询末尾使用一个或两个连字符。 这些标志覆盖服务器配置：
- **引擎：** `-brave`、`--dd` 等（优先尝试该引擎）
- **引用：** `--cite`（包括参考文献）、 `--no-cite`（省略参考文献）
- **思考（研究）：** `--think` 或 `-think` — 对多个搜索引擎运行相同的查询（前3个），合并结果按URL，并返回编译的研究，带有“来源”列。用于深入研究。
每个搜索响应都以 **via [搜索引擎] [表情符号]** 开头（例如 `via DuckDuckGo :D`）；每个读取响应都以 **via [URL] [:]** 开头。
当启用引用时，模型被指示在答案主体中包含 **内联引用** [1]、[2] 等（在句子或事实旁边）和底部的 **参考文献** 部分；每个编号都与同一来源匹配（维基百科风格）。
**如果您看不到 "via ..." 或引用链接：** 模型未调用 `search_web` 工具（例如“模型未能生成工具调用”）。使用支持工具/函数调用的模型，或尝试再次查询。 服务器始终在实际调用工具时返回“via ...”和引用。
| 标志（完整） | 缩写 | 引擎 |
| --- | --- | --- |
| `--duckduckgo` | `--dd` | DuckDuckGo |
| `--brave` | `--b` | Brave |
| `--bing` | `--bi` | Bing |
| `--google` | `--g` | Google |
| `--ecosia` | `--ec` | Ecosia |
| `--startpage` | `--sp` | Startpage |
| `--qwant` | `--qw` | Qwant |
| `--yahoo` | `--yh` | Yahoo |
| `--yandex` | `--ya` | Yandex |
## 搜索引擎
搜索引擎按顺序尝试。如果第一个搜索引擎失败或返回无结果，则自动尝试下一个。
| ID | 名称 | 备注 |
| --- | --- | --- |
| `duckduckgo` | DuckDuckGo | 默认首选。HTML端点，非常可靠 |
| `brave` | Brave Search | 良好的隐私保护替代方案 |
| `bing` | Bing | 微软的搜索引擎 |
| `google` | Google | 可能对纯HTTP请求（验证码）不太可靠 |
| `ecosia` | Ecosia | Bing提供，种植树木与广告收入 |
| `startpage` | Startpage | Google结果与隐私保护，可能需要cookie |
| `qwant` | Qwant | 欧洲隐私保护引擎（使用Lite HTML） |
| `yahoo` | Yahoo | 经典搜索引擎，解包重定向URL |
| `yandex` | Yandex | 俄罗斯搜索引擎，支持英文 |
默认顺序： `duckduckgo, brave, bing, google, ecosia, startpage, qwant, yahoo, yandex`
使用 `--engines brave,duckduckgo` （CLI）、 `WEB_SEARCH_ENGINES=brave,duckduckgo` （环境变量）或 `"engines": ["brave", "duckduckgo"]` （配置文件）自定义。
每个搜索引擎在 `src/engines/` 中都有自己的解析器 — 容易维护、修复或添加新的。
## 配置
所有功能均开箱即用。通过三个层次覆盖任何设置（优先级最高）：
### 1. CLI标志
```bash
npx simple-web-search-mcp --engines brave,duckduckgo --max-results 5 --timeout 20000
```
| 标志 | 默认值 | 描述 |
| --- | --- | --- |
| `--log` | 关闭 | 将日志写入 `~/.simple-web-search-mcp/logs/` （每日文件 `YYYY-MM-DD.log`） |
| `--cite` | — | 在搜索结果中包含维基百科风格的参考文献（覆盖配置） |
| `--no-cite` | — | 在搜索结果中省略参考文献部分（覆盖配置） |
| `--engines <list>` | 所有9个引擎 | 逗号分隔的引擎顺序 |
| `--max-results <n>` | `10` | 返回的最大搜索结果数 |
| `--timeout <ms>` | `15000` | HTTP请求超时 |
| `--rate-limit <ms>` | `1000` | 对同一主机的请求的最小延迟 |
| `--max-retries <n>` | `3` | 429/503/网络错误时的重试次数 |
| `--max-content-length <n>` | `12000` | 返回的页面内容的最大字符数 |
| `--user-agent <string>` | Chrome UA | 自定义用户代理头 |
| `--config <path>` | — | JSON配置文件路径 |
### 2. 环境变量
```bash
WEB_SEARCH_ENGINES=brave,duckduckgo WEB_SEARCH_MAX_RESULTS=5 npx simple-web-search-mcp
```
| 变量 | 映射到 |
| --- | --- |
| `WEB_SEARCH_LOG` | 启用文件日志（设置为 `1`、`true` 或 `yes`） |
| `WEB_SEARCH_CITATIONS` | `citations` — `1`/`true`/`yes` 包括参考文献， `0`/`false`/`no` 省略 |
| `WEB_SEARCH_ENGINES` | `engines` |
| `WEB_SEARCH_MAX_RESULTS` | `maxResults` |
| `WEB_SEARCH_TIMEOUT` | `timeoutMs` |
| `WEB_SEARCH_RATE_LIMIT` | `rateLimitMs` |
| `WEB_SEARCH_MAX_RETRIES` | `maxRetries` |
| `WEB_SEARCH_MAX_CONTENT_LENGTH` | `maxContentLength` |
| `WEB_SEARCH_USER_AGENT` | `userAgent` |
| `WEB_SEARCH_CONFIG` | 配置文件路径 |
### 3. 配置文件
服务器按以下顺序查找JSON配置文件：
1. `--config <path>` （CLI标志）
2. `$WEB_SEARCH_CONFIG` （环境变量）
3. `./.simple-web-search.json` （项目本地）
4. `~/.simple-web-search/config.json` （用户级别）
示例配置文件：
```json
{
"engines": ["brave", "duckduckgo", "bing"],
"maxResults": 5,
"timeoutMs": 20000,
"rateLimitMs": 2000,
"maxRetries": 2,
"maxContentLength": 8000,
"citations": true
}
```
设置 `"citations": false` 以省略搜索结果中的参考文献部分。 在运行时使用 `--cite` 或 `--no-cite` 覆盖。
## 安全
所有输入和输出都经过净化：
- **输入验证** — 查询被修剪、限制长度（400个字符）并剥离控制字符
- **URL验证** — 仅允许 `http:` 和 `https:` 方案；阻止 `javascript:`、`data:`、`file:` 等
- **HTML剥离** — 从提取的文本中删除所有HTML标签，然后输出
- **控制字符删除** — 从所有输出中剥离二进制/控制字符
- **Markdown注入转义** — 从抓取的标题中转义特殊字符，以免破坏markdown链接语法
- **内容隔离** — 抓取的页面内容用视觉分隔符清晰隔离，以便LLM可以将其与指令区分开
- **输出为纯文本** — 服务器仅返回markdown格式的文本，从不返回原始HTML或可执行内容
## 速率限制
内置的速率限制保护您和搜索引擎：
- **每个主机限制** — 强制对同一主机名的请求之间的最小延迟（默认1秒）
- **自动重试** — 重试HTTP 429（请求过多）和503（服务不可用）
- **指数退避** — 1秒、2秒、4秒、8秒（上限15秒）之间的重试
- **尊重`Retry-After`** — 如果存在，服务器的重试后头部将被遵守
- **可配置** — 根据需要调整 `rateLimitMs` 和 `maxRetries`
## 项目结构
```
src/
index.ts MCP服务器 — 工具、提示、启动
config.ts 配置加载（CLI > 环境变量 > 文件 > 默认值）
logger.ts 可选文件日志（~/.simple-web-search-mcp/logs/，启用 --log）
parse-search-input.ts 解析/search输入以获取尾随 --engine / --abbrev标志
search.ts SearchClient — 协调引擎 + 页面读取
sanitize.ts 输入/输出净化
rate-limiter.ts 每个主机限制 + 重试和退避
engines/
types.ts SearchEngine接口
index.ts 引擎注册 + 默认顺序
duckduckgo.ts DuckDuckGo HTML解析器
brave.ts Brave Search解析器
bing.ts Bing解析器
google.ts Google解析器
ecosia.ts Ecosia解析器
startpage.ts Startpage解析器
qwant.ts Qwant Lite解析器
yahoo.ts Yahoo解析器
yandex.ts Yandex解析器
tests/
sanitize.test.ts 净化单元测试
engines.test.ts 引擎解析器单元测试（所有9个引擎）
config.test.ts 配置加载单元测试
rate-limiter.test.ts 速率限制单元测试
fixtures/ 每个引擎的模拟HTML
```
## 要求
- Node.js 18 或更高版本
## 开发
```bash
git clone <仓库网址>
cd simple-web-search-mcp
npm install
npm run build
npm start
```
### 脚本
| 脚本 | 描述 |
| --- | --- |
| `npm test` | 运行单元测试（vitest） |
| `npm run test:watch` | 在监视模式下运行测试 |
| `npm run lint` | 使用Biome进行代码检查 |
| `npm run lint:fix` | 自动修复代码检查问题 |
| `npm run format` | 使用Biome进行格式化 |
| `npm run docs` | 生成API文档（TypeDoc） |
| `npm run build` | 编译TypeScript |
| `npm start` | 启动服务器 |
## 许可证
MIT
