SearXNG MCP Server

一个基于 FastMCP 实现的 SearXNG 搜索 MCP 服务，使用 Streamable HTTP 传输，支持本地运行与 Docker 部署。

SearXNG相关链接:

官方文档:https://docs.searxng.org/

在线示例:https://searx.space/

功能

• 暴露 MCP 工具 search(query)：根据关键字调用 SearXNG 实例并返回搜索结果摘要。
• 通过 HTTP 端点 http://<host>:<port>/mcp 提供 MCP 服务，便于远程 / 跨域调用。
• 采用 无状态（stateless） Streamable HTTP 模式，客户端无需维护 Mcp-Session-Id，可直接并发调用。
• 支持通过环境变量自定义 SearXNG 实例地址，方便私有化部署。

环境变量

| 变量名 | 默认值 | 说明 | | ------------- | -------------------- | ----------------------------------------------------- | | SEARXNG_URL | https://searxng.abc.com | SearXNG 实例根地址（要求开启JSON） | | HOST | 0.0.0.0 | 服务监听地址 | | PORT | 9000 | 服务监听端口 |

本地运行

# 安装依赖（建议使用虚拟环境）
pip install -r requirements.txt

# 可选：自定义 SearXNG 实例（只需填根地址）
export SEARXNG_URL="https://your-searxng-instance"

# 启动服务
python Server.py

启动后，MCP 端点为：

http://localhost:9000/mcp

Docker 部署

构建镜像

docker build -t searxng-mcp .

运行容器

docker run -d \
  --name searxng-mcp \
  -p 9000:9000 \
  -e SEARXNG_URL="https://searxng.abc.com" \
  searxng-mcp

如需修改端口，可同时覆盖容器内外端口与 PORT：

docker run -d \
  --name searxng-mcp \
  -p 8080:8080 \
  -e PORT=8080 \
  searxng-mcp

使用在线镜像

docker run -d \
  --name searxng-mcp \
  -p 9000:9000 \
  -e SEARXNG_URL="https://searxng.abc.com" \
  muzihuaner/searxng-mcp:latest

访问地址

部署完成后，MCP 端点格式为：

http://<你的服务器域名或IP>:<端口>/mcp

例如：http://localhost:9000/mcp 或 https://mcp.your-domain.com/mcp

客户端配置

在支持 Streamable HTTP 的 MCP 客户端中，将服务地址填写为上面的 /mcp 端点即可，例如：

{
  "mcpServers": {
    "searxng": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

工具说明

search(query: str) -> str

根据关键字调用 SearXNG 搜索，返回各结果条目的 content 文本，以换行拼接。

• query：搜索关键字。
• 返回：搜索结果的文本内容；请求失败时返回 False。

并发与性能

测试结果示例（局域网 / 上游 `so.xxx.cn`）：

总请求数 : 100 并发 worker : 50 成功 : 100 失败 : 0 总耗时(秒) : 67.68 吞吐(QPS) : 1.48 平均延迟(秒) : 27.284 最小延迟(秒) : 7.203 最大延迟(秒) : 44.418

> 注意：端到端延迟主要取决于 SearXNG 上游实例的响应速度（本例平均约 27s 来自上游 `so.xxx.cn` 较慢），服务本身可稳定承载并发且零失败。若需提升吞吐，可：
> - 换用响应更快 / 自托管的 SearXNG 实例（通过 `SEARXNG_URL` 指定）；

常见问题

Q: 客户端报错 Missing session ID？ A: 本服务已启用 stateless_http=True，无需 session。若仍报该错，请确认客户端指向的是 /mcp 端点。

Q: 如何在生产环境收紧 CORS？ A: 编辑 Server.py 中的 CORSMiddleware，将 allow_origins=["*"] 改为具体来源列表，如 ["https://your-domain.com"]。