searxng-mcp

一个用于 SearXNG 的 MCP 服务器，它保持模型可见的输出简短，在隐藏的元数据中保留完整的搜索结果负载，并支持本地 stdio 客户端和已部署的 streamable-http 使用场景。

你将获得

• search：用于简洁的网页搜索，并在 _meta 中包含完整的原始负载

• search_many：用于并行扇出、去重和合并排名

• search_and_fetch：在一次调用中完成搜索和源提取

• research：用于多查询搜索，包含批量获取和合并源

• fetch_url：用于带引用的可读页面提取

• fetch_many：用于带缓存的并行 URL 提取

• health：用于后端、缓存和渲染状态检查

该服务器设计轻量。SearXNG 负责搜索工作；searxng-mcp 处理工具塑造、缓存、提取和传输。

Related MCP server: SearXNG MCP Bridge

快速入门

从检出代码安装

uv sync
uv run searxng-mcp

使用 uvx 安装

searxng-mcp 从此仓库分发（无 PyPI 发布）。最快路径是：

uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp

默认安装中包含渲染获取功能。如果主机已安装 Chromium 或 Chrome，searxng-mcp 将直接使用它。否则，首次渲染获取会自动将 Playwright Chromium 引导至用户缓存中。

使用 Docker 运行

docker build -t searxng-mcp .
docker run --rm -p 8811:8811 --add-host=host.docker.internal:host-gateway \
  -e SEARXNG_MCP_BASE_URL=http://host.docker.internal:8890 \
  searxng-mcp

Claude Desktop 示例

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/88plug/searxng-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_MCP_BASE_URL": "http://127.0.0.1:8890",
        "SEARXNG_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

部署模式

本地 stdio

适用于桌面客户端和私有工作流。这是最简单且最安全的模式。

SEARXNG_MCP_TRANSPORT=stdio uv run searxng-mcp

可流式传输 HTTP

适用于私有服务、团队部署或反向代理的内部端点。

SEARXNG_MCP_TRANSPORT=streamable-http uv run searxng-mcp --host 0.0.0.0 --port 8811

加固的 Docker 和 Compose

对于长期运行的自托管服务，请使用加固的容器变体和提供的 Compose 堆栈。

docker build -f Dockerfile.prod -t searxng-mcp:prod .
cp docker-compose.env.example .env
docker compose up --build -d

安全与信任

本项目适用于本地和受信任的网络环境。它不是一个即插即用的公共互联网服务。

• fetch_url 和 fetch_many 可以获取客户端提供的任意 URL

• 渲染提取可能会针对不受信任的页面启动 Chromium

• streamable-http 在任何共享部署中都应置于身份验证或反向代理之后

• SEARXNG_MCP_FETCH_VERIFY_TLS=0 仅用于私有或自签名后端设置

如果你暴露了 HTTP 传输，请将其视为内部服务，并添加任何具备 SSRF 能力的工具所应有的控制措施。

为什么存在此项目

• 紧凑的模型可见输出，同时在隐藏元数据中保留完整细节

• 通过并行搜索和获取扇出实现更快速的研究工作流

• 针对 JS 密集型页面的渲染提取，无需额外的安装标志

• 为希望拥有自己基于 SearXNG 的 MCP 服务器的用户提供可自托管的部署

MCP 界面

• searxng://config 暴露当前设置、传输模式和渲染支持

• searxng://guide 总结了可用工具及其使用时机

• quick_lookup、deep_research 和 research_workflow 是针对支持提示词界面的客户端的可选兼容性提示词

环境

关键变量：

• SEARXNG_MCP_BASE_URL: SearXNG 基础 URL，默认为 http://127.0.0.1:8890

• SEARXNG_MCP_FALLBACK_BASE_URLS: 可选的逗号分隔的备用 SearXNG 实例

• SEARXNG_MCP_TRANSPORT: stdio、streamable-http 或 sse

• SEARXNG_MCP_SEARCH_TIMEOUT: 后端搜索超时（秒）

• SEARXNG_MCP_FETCH_TIMEOUT: 获取超时（秒）

• SEARXNG_MCP_SEARCH_CACHE_TTL: 搜索缓存 TTL（秒）

• SEARXNG_MCP_FETCH_CACHE_TTL: 获取缓存 TTL（秒）

• SEARXNG_MCP_FETCH_VERIFY_TLS: 设置为 0 以跳过获取时的 TLS 验证

• SEARXNG_MCP_RENDER_TIMEOUT: 渲染获取的浏览器导航超时

• SEARXNG_MCP_RENDER_WAIT_MS: 渲染获取在 DOM 内容加载后的额外等待时间

• SEARXNG_MCP_RENDER_CONCURRENCY: 并发渲染获取限制

• SEARXNG_MCP_RENDER_HEADLESS: 设置为 0 以显示浏览器

• SEARXNG_MCP_RENDER_BROWSER_PATH: 显式的 Chromium 或 Chrome 二进制路径

• SEARXNG_MCP_RENDER_SANDBOX: 设置为 1 以保持 Chromium 沙盒启用

• SEARXNG_MCP_RENDER_BLOCK_RESOURCES: 设置为 0 以允许渲染期间的图像、字体、样式表和媒体

• SEARXNG_MCP_RENDER_AUTO_FALLBACK: 设置为 0 以禁用自动渲染回退

• SEARXNG_MCP_RENDER_AUTO_MIN_WORDS: 降低此值可使自动渲染更激进

• SEARXNG_MCP_RENDER_AUTO_MIN_CHARS: 降低此值可使自动渲染更激进

• SEARXNG_MCP_CACHE_DIR: 缓存目录路径

基准测试

uv run searxng-mcp-bench --rounds 3

基准测试报告：

• 原始 SearXNG 后端延迟

• Token 可见的搜索输出大小

• 合并的多查询搜索延迟

• 多查询研究延迟

• 获取提取延迟

• 渲染获取延迟

• 批量获取提取延迟

• 渲染批量获取延迟

文档

• 文档站点概览

• 入门指南

• 部署

• 安全

• 工具参考

• 客户端配置

• 对比

• 更新日志

• SearXNG 文档

构建与测试

uv sync --all-groups
uv run pytest -q
uv run python -m compileall src
uv run mkdocs build --strict

依赖维护

手动检查：

uv lock --upgrade --dry-run
uvx --from pip-audit pip-audit

自动化检查：

• 每周针对 uv 依赖项和 GitHub Actions 的 Dependabot PR

• 每周用于漏洞扫描和升级预演的 Dependency Health 工作流