内容
# searxng-mcp
一款将 [SearXNG](https://github.com/searxng/searxng) 和 [模型上下文协议](https://modelcontextprotocol.io) 服务器捆绑在一起的单一 Docker 镜像，公开网络搜索和页面抓取作为 MCP 工具。
无需单独的 SearXNG 容器 - 只需运行镜像。
## 使用方法
```bash
# STDIO（Claude Code / Cursor / Copilot / OpenCode）
docker run --rm -i dandehoon/searxng-mcp:latest
# HTTP 流媒体（远程 / 多客户端）
docker run --rm -p 8000:8000 -e SEARXNG_MCP_TRANSPORT=http dandehoon/searxng-mcp:latest
```
<details>
<summary>Claude Code</summary>
```bash
claude mcp add --transport stdio searxng -- docker run --rm -i dandehoon/searxng-mcp:latest
```
或添加到项目根目录中的 `.mcp.json`（项目范围）或 `~/.claude.json`（用户范围）：
```json
{
"mcpServers": {
"searxng": {
"command": "docker",
"args": ["run", "--rm", "-i", "dandehoon/searxng-mcp:latest"]
}
}
}
```
</details>
<details>
<summary>GitHub Copilot</summary>
`.vscode/mcp.json`（或 `MCP: Open User Configuration` 以获取全局配置）：
```json
{
"servers": {
"searxng": {
"command": "docker",
"args": ["run", "--rm", "-i", "dandehoon/searxng-mcp:latest"]
}
}
}
```
</details>
<details>
<summary>Cursor</summary>
`.cursor/mcp.json`（或 `~/.cursor/mcp.json` 以获取全局配置）：
```json
{
"mcpServers": {
"searxng": {
"command": "docker",
"args": ["run", "--rm", "-i", "dandehoon/searxng-mcp:latest"]
}
}
}
```
</details>
<details>
<summary>OpenCode</summary>
```bash
opencode mcp add searxng -- docker run --rm -i dandehoon/searxng-mcp:latest
```
或添加到项目根目录中的 `opencode.json`（或 `~/.config/opencode/opencode.json` 以获取全局配置）：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"searxng": {
"type": "local",
"command": ["docker", "run", "--rm", "-i", "dandehoon/searxng-mcp:latest"]
}
}
}
```
</details>
## 构建
```bash
# 使用固定的 SearXNG 基础镜像构建（参见 Dockerfile）
docker build -t searxng-mcp:latest .
# 覆盖 SearXNG 基础标签
docker build --build-arg SEARXNG_VERSION=2026.5.26-0037d43d8 -t searxng-mcp:latest .
```
然后在上述任何客户端配置中使用 `searxng-mcp:latest` 代替注册表镜像。
## 工具
| 工具 | 描述 |
| ------------ | ------------------------------------------------------------------------------------ |
| `search-web` | 通过 SearXNG 搜索网络。返回标题、网址、摘要和相关性评分。 |
| `fetch-web` | 获取网址并返回其内容作为可读的 Markdown 文本。 |
### `search-web` 参数
| 参数 | 类型 | 默认值 | 描述 |
| ------------- | ------ | -------------------- | ---------------------------------------- |
| `query` | 字符串 | — | 搜索查询（必填） |
| `categories` | 字符串 | `$SEARXNG_CATEGORIES` | SearXNG 类别（例如 `news`、`images`） |
| `language` | 字符串 | `$SEARXNG_LANGUAGE` | 语言代码（例如 `en`、`fr`）。`auto` 以检测。 |
| `pageno` | 整数 | `1` | 结果页码 |
| `max_results` | 整数 | `$SEARXNG_MCP_MAX_RESULTS` | 返回的最大结果数 |
`safesearch`、`time_range` 和 `engines` 不作为工具参数公开 - 而是配置环境变量。
### `fetch-web` 参数
| 参数 | 类型 | 描述 |
| --------- | ------ | ----------------------- |
| `url` | 字符串 | 要获取的网址（必填） |
HTML 在返回之前转换为 Markdown - `<script>`、`<style>`、`<nav>`、`<footer>` 和 `<aside>` 标签被剥离。
## 环境变量
| 变量 | 默认值 | 描述 |
| ---------------------- | ----------------------- | ---------------------------------------- |
| `SEARXNG_MCP_TRANSPORT` | `stdio` | 传输模式：`stdio`、`http` 或 `streamable-http` |
| `SEARXNG_LOG_LEVEL` | `WARNING` | MCP 服务器的 Python 日志级别 |
| `SEARXNG_URL` | `http://127.0.0.1:8080` | SearXNG 基本网址（内部） |
| `SEARXNG_TIMEOUT` | `30.0` | 搜索 HTTP 超时（秒） |
| `SEARXNG_FETCH_TIMEOUT` | `60.0` | 网址获取 HTTP 超时（秒） |
| `SEARXNG_HOST` | `0.0.0.0` | 绑定主机（仅 HTTP 传输） |
| `SEARXNG_PORT` | `8000` | 绑定端口（仅 HTTP 传输） |
| `SEARXNG_MCP_PATH` | `/mcp/` | 网址路径（仅 HTTP 传输） |
| `SEARXNG_CATEGORIES` | `general` | 默认搜索类别 |
| `SEARXNG_LANGUAGE` | `auto` | 默认语言代码 |
| `SEARXNG_MCP_MAX_RESULTS` | `20` | 返回的最大结果数 |
| `SEARXNG_SAFESEARCH` | `0` | 安全搜索：`0` = 关闭、`1` = 中度、`2` = 严格 |
| `SEARXNG_TIME_RANGE` | — | 按时间过滤：`day`、`week`、`month` 或 `year` |
| `SEARXNG_ENGINES` | — | 强制使用的逗号分隔引擎（例如 `google,bing`） |
## 架构
```
docker run --rm -i searxng-mcp
│
├── entrypoint.sh
│ ├── 在 127.0.0.1:8080 上启动 granian（SearXNG WSGI 服务器）
│ ├── 等待 /healthz
│ └── 执行 → MCP 服务器（STDIO 或 HTTP）
│
└── MCP 服务器（fastmcp）
├── search-web → httpx → SearXNG JSON API
└── fetch-web → httpx → 远程网址 → markdownify
```
构建在固定的 `docker.io/searxng/searxng:<date>-<sha>` 标签上 - 无需重新编译 C 扩展。 在 `Dockerfile` 中增加标签（`ARG SEARXNG_VERSION`）以更新 SearXNG。
## 开发
```bash
make install-dev # 安装开发依赖
make test # 单元测试（无 Docker）
make test-all # 构建镜像 + E2E MCP 握手测试
make lint # ruff + mypy
```
## 许可证
[MIT](LICENSE)
