SearXNG 本地部署与 MCP 接入：搭建私有搜索引擎做技术文档交叉验证

开篇：SearXNG 是什么，为什么要自己部署

SearXNG 是一个开源元搜索引擎（meta search engine）—— 它本身不爬取网页，而是把用户查询转发给百度、必应、谷歌等上游引擎，聚合结果后统一返回。 部署在本地 Docker 中，免费、无 API Key、无调用次数限制、无搜索历史泄漏。

本文从零开始，完成 SearXNG 本地部署、中文引擎配置、JSON API 开启， 再通过 MCP 协议接入 Claude Code，最后给出三个真实使用场景和一套搜索策略。

一、SearXNG 本地部署

前置条件：Docker 已安装（Windows 使用 Docker Desktop + WSL2 后端，macOS 使用 Docker Desktop，Linux 使用 Docker Engine）。 以下命令三端通用。

1.1 拉取镜像并启动

国内 Docker 镜像加速：如果 docker pull 极慢或超时，搜索 "Docker 国内镜像加速 2026" 获取当前可用的镜像站地址， 写入 Docker Desktop Settings → Docker Engine → registry-mirrors。

1.2 配置：开启中文引擎 + JSON API

默认配置不会启用百度和 JSON API。需要导出 settings.yml 并修改——推荐用 volume mount 方式（容器删除后配置不丢失），不推荐 docker exec vi。

需要改三个地方：

secret_key 用于服务端会话加密，生产环境务必改为随机值（openssl rand -hex 32 生成）。

1.3 验证搜索引擎

如果返回 403，说明 formats 列表中缺少 json，回头检查 settings.yml。

二、接入 Claude Code MCP

SearXNG 有多个社区 MCP 服务器。本文使用 mcp-searxng（npm）， 它提供两个工具：

• searxng_web_search — 执行搜索，支持分页、语言、时间范围、安全搜索参数
• web_url_read — 读取搜索结果中 URL 的全文内容

2.1 Windows 平台的 MCP 配置

不推荐手动编辑 JSON 配置文件。使用 Claude Code 自带的 claude mcp add 命令：

⚠️ 常见坑：claude mcp add 在 Windows 上可能把 /c 误解析为 C:/。 这是因为 Git for Windows 的 MSYS2/Cygwin 环境将 POSIX 路径 /c 自动转为 Windows 路径。 添加后检查 .claude.json 中 args 第一个元素是否为 "/c"，如果变成 "C:/" 则手动改回。

最终生效的配置（位于 .claude.json 中当前项目的 mcpServers 下）：

2.2 验证 MCP 连接

重启 Claude Code 后，输入 /mcp 确认 searxng 状态为 connected ✓。

如果 connected 但搜索工具调用报错 "not configured"，手动验证 MCP 进程收到的 URL：

三、使用示例

SearXNG 接入 Claude Code 后，MCP 工具可以在对话中直接被 Claude Code 调用。以下是三个典型场景。

3.1 技术选型调研

同一个问题在不同搜索引擎中得到的结果侧重不同。例如搜 Bun vs Node.js performance 2026：

• 百度：返回中文社区（掘金、SegmentFault、CSDN）的对比评测，侧重国内开发者的实际体验
• 必应：覆盖英文技术博客和 Microsoft 生态内容，对 npm 包的文档页面索引较好
• 谷歌：优先返回官方 benchmark 和 GitHub 仓库的 issue 讨论，时效性排序更强

聚合三方的结果可以避免单一引擎的信息偏差——中文社区可能更关注生态兼容性，英文社区更关注裸性能数据。

3.2 报错排查

遇到一段报错信息时，直接粘贴到搜索中，跨社区对比解决方案。 例如一段 Docker 启动报错 Error response from daemon: Ports are not available：

• 百度会优先返回 CSDN/博客园的同类踩坑帖，包含中文环境下的操作步骤截图
• 必应返回 Stack Overflow 和 Microsoft 官方文档中关于 Windows 端口占用的说明
• 谷歌返回 GitHub Issues 中 Docker 项目的相关 bug report，可能包含官方回复

三个答案源互相参照，可以判断哪个方案是"大多数情况下有效"的，哪个是特定环境下的 workaround。

3.3 API 参数或配置字段核实

需要确认某个 API 参数名或配置字段的准确写法时，分别在中文和英文社区搜索。 例如查 Next.js basePath 的配置方式：

• 英文搜索结果直接指向 Next.js 官方 docs（nextjs.org/docs），信息最权威
• 中文搜索结果可能包含国内开发者的实战文章，附带 Edge Case（如 basePath 与 assetPrefix 的区别和组合使用）

两者结合——官方文档确认正确性，社区文章确认边界情况——比只看单源更可靠。

四、搜索策略与引擎调优

4.1 引擎选择策略

4.2 搜索技巧

• 站点限定：site:github.com 关键词 将搜索限定在 GitHub；site:csdn.net 限定在 CSDN。排除噪音时特别有用。
• 时间过滤：SearXNG JSON API 支持 time_range 参数 （day / month / year），过滤掉过时信息。 例如搜索 q=claude-code-mcp&time_range=year 只看一年内的内容。
• 多关键词组合：先用宽泛词（如 Docker 网络配置）定位问题域， 再用精确词（如 docker bridge network iptables）深入。 SearXNG 的聚合特性让切换引擎的成本为零——同一组关键词在不同引擎中跑一次即可。
• 语言参数：设置 language: en 强制返回英文结果，language: zh 返回中文结果。跨语言对比同一技术话题时很有用。

4.3 为什么用 SearXNG 而不是直接搜

• 免费无 Key：不需要注册任何搜索 API 服务，Docker 一个容器跑起来就是搜索引擎
• 多引擎聚合：同一个查询同时覆盖百度 + 必应 + 谷歌，中英文资料一次返回
• 无跟踪：搜索请求从本机发出，搜索历史不过第三方服务器
• 可编程：JSON API 让 Claude Code 直接调用搜索结果，不需要手动打开浏览器
• 备选方案：如果暂时不想部署 SearXNG，Claude Code 内置的 WebSearch + WebFetch 也能完成大部分搜索需求——只是搜索源受限于单一引擎索引

五、常见问题

Docker pull 超时或极慢

国内网络环境下，Docker Hub 的访问速度不稳定。配置 Docker 镜像加速器 （Docker Desktop → Settings → Docker Engine → registry-mirrors）， 或在搜索引擎中搜 "Docker 国内镜像加速 2026" 获取当前可用的加速地址。

JSON API 返回 403

settings.yml 中 search.formats 列表缺少 json。 添加后 docker restart searxng 即可。

MCP 显示 connected 但搜索失败

参考 2.2 节，手动启动 MCP 进程确认 SEARXNG_URL 是否正确传入。

常见原因：

• SearXNG 容器未启动（docker ps --filter name=searxng 确认）
• 端口被占用（netstat -ano | findstr 8080 检查）
• Windows 下用了 env 块配置（参考 2.1 节的绕过方案）

修改 settings.yml 后不生效

如果使用的是 docker cp 方式修改，确认执行了 docker restart searxng。 如果使用的是 volume mount（-v ./settings.yml:/etc/searxng/settings.yml）， 注意 SearXNG 在启动时会校验配置，有语法错误时容器会直接退出——先 docker logs searxng 查看错误信息。