1. 为什么我要给 Claude Code 换掉内置搜索用 Claude Code 写代码的人大概率都遇到过这个场景让它查一个中文技术问题返回的结果要么是几年前的英文博客要么干脆答非所问。内置的 WebSearch 工具在英文技术检索上还算能用但一碰到中文内容就明显吃力——覆盖的站点少、时效性差、摘要信息也不够。我试过在对话里手动贴搜索结果给它但这样每次都要切浏览器、复制粘贴效率很低。后来想到一个思路既然 Claude Code 支持 MCPModel Context Protocol接入外部工具那能不能把 SearXNG 这个开源的元搜索引擎挂上去让它成为默认的联网检索通道SearXNG 本身不抓网页它把 Google、DuckDuckGo、百度、搜狗这些引擎的查询结果聚合起来去重排序后返回。核心卖点有三个一是隐私不记录搜索历史、不追踪用户行为二是多引擎聚合一次查询覆盖多个来源三是本地部署数据完全在自己机器上。对开发者来说还有一个隐性好处——它提供 JSON 格式输出程序调用非常方便。这篇文章就是记录我把 SearXNG 通过 MCP 接进 Claude Code 的完整过程包括 Docker 启动参数、MCP 配置骨架、权限设置以及实测下来的搜索质量、响应速度和踩过的坑。如果你也在用 Claude Code 做日常开发检索这套方案可以直接复制。2. 前置准备SearXNG 与 MCP 工具链在动手之前先把需要的东西理清楚。整个链路是这样的Claude Code 通过 MCP 协议调用一个本地的 MCP Server这个 Server 再去请求运行在 localhost 上的 SearXNG 实例SearXNG 负责向各个搜索引擎发起查询并聚合结果。需要准备的东西不多Docker 环境用来跑 SearXNG 容器Node.js 环境用来装 mcp-searxng 这个 MCP ServerClaude Code 已经能正常使用一个可用的模型接入点我用的是 TaoToken 的 API 通道配置简单模型对话和 Coding Plan 都能覆盖关于模型接入这块如果你还没配好 Claude Code 的 API可以先到官网看一下接入方式。TaoToken 提供了兼容 Anthropic 协议的接口Claude Code 直接填 API Key 就能用。具体来说API 地址是https://taotoken.net/api在 Claude Code 的环境变量里设置ANTHROPIC_BASE_URL指向这个地址即可。API Key 在控制台的 API Keys 页面生成模型对话和 Coding Plan 共用同一套凭证。这里有个细节要注意SearXNG 的 Google 引擎查询是由服务端发出的也就是说你的 SearXNG 容器需要能访问到 Google。如果你的部署环境本身网络可达那不用额外配置如果不行可以在 Docker Compose 里给容器指定出口但这不是本文重点后面排障部分会简单提一下。MCP Server 这边我用的是mcp-searxng这个 npm 包全局安装后会在/opt/homebrew/bin/下生成可执行文件macOS Homebrew 环境。Linux 下路径可能是/usr/local/bin/Windows 下则是 npm 全局目录配置时按实际路径填。3. 可复制配置从 Docker 到 MCP 全流程3.1 SearXNG 容器启动先建一个工作目录比如~/searxng在里面放docker-compose.ymlservices: searxng: image: searxng/searxng:latest ports: - 8787:8080 volumes: - ./settings.yml:/etc/searxng/settings.yml:ro environment: - SEARXNG_BASE_URLhttp://localhost:8787/ restart: unless-stopped端口映射这里我把宿主机的 8787 映射到容器的 8080你可以改成别的只要后面 MCP 配置里的SEARXNG_URL跟着改就行。SEARXNG_BASE_URL这个环境变量影响的是 SearXNG 自己生成的链接本地用的话填 localhost 加端口即可。3.2 settings.yml 引擎配置SearXNG 默认启用的引擎很多但实际用下来引擎数量过多会明显拖慢响应。我精简到 9 个核心引擎覆盖中英文技术检索和新闻场景use_default_settings: true server: secret_key: change-this-to-a-random-string limiter: false image_proxy: false search: safe_search: 0 default_lang: zh-CN formats: - html - json engines: - name: google engine: google weight: 5 disabled: false - name: google news engine: google_news weight: 4 disabled: false - name: duckduckgo engine: duckduckgo weight: 5 disabled: false - name: duckduckgo news engine: duckduckgo_news weight: 3 disabled: false - name: baidu engine: baidu weight: 4 disabled: false - name: baidu news engine: baidu_news weight: 3 disabled: false - name: sogou engine: sogou weight: 3 disabled: false - name: sogou news engine: sogou_news weight: 3 disabled: false - name: bing engine: bing weight: 2 disabled: true几个关键参数说明一下。safe_search: 0是关掉安全搜索过滤开发场景下不需要这层过滤关掉后结果更全。formats里加上json是为了让 MCP Server 能解析结构化数据默认只有 html。default_lang: zh-CN让中文查询更精准不用每次手动指定语言。limiter: false是关掉速率限制本地自用没必要限流。引擎权重方面Google 和 DuckDuckGo 给到 5因为英文技术文档质量最高百度和搜狗给 3 到 4作为中文内容的补充。Bing 我暂时禁用了实测下来它的结果和 Google 重叠度高但质量不如后者留着只会增加响应时间。3.3 安装 MCP Servernpm install -g mcp-searxng装完后确认一下可执行文件路径which mcp-searxngmacOS Homebrew 环境下通常是/opt/homebrew/bin/mcp-searxng记下这个路径下一步要用。3.4 Claude Code MCP 配置编辑~/.claude/settings.local.json加入 MCP Server 定义和权限授权{ mcpServers: { searxng: { command: /opt/homebrew/bin/mcp-searxng, env: { SEARXNG_URL: http://localhost:8787 } } }, permissions: { allow: [ mcp__searxng__searxng_web_search, mcp__searxng__web_url_read, mcp__searxng__searxng_instance_info ] } }command填你上一步which出来的实际路径。SEARXNG_URL要和 Docker 端口映射一致。权限部分至少授权searxng_web_search和web_url_read两个前者是搜索后者是读取网页内容searxng_instance_info用来查询实例状态可选但建议加上。3.5 CLAUDE.md 全局设定在~/.claude/CLAUDE.md里加一段让 Claude Code 默认走 SearXNG 而不是内置搜索## 搜索配置 **默认使用 MCP SearXNG 搜索不要使用内置 WebSearch 工具。** 通过 MCP 调用 searxng server已配置使用其提供的搜索工具。 SearXNG 运行在 http://localhost:8787中英文联网搜索主要配置引擎Google、DuckDuckGo、百度、搜狗。这段设定的作用是给 Claude Code 一个明确的指令优先级。实测下来如果不写这段它有时候还是会优先调内置 WebSearch写了之后基本都会走 MCP 通道。4. 验证请求与实测结果4.1 先确认 SearXNG 本身可用在配置 Claude Code 之前先用 curl 确认 SearXNG 能正常返回 JSONcurl -s http://localhost:8787/search?qPython异步编程formatjson | jq .results | length如果返回一个大于 0 的数字说明 SearXNG 工作正常。如果报错或者返回 0先检查容器是否在运行docker ps | grep searxng再检查/config端点能否访问curl -s http://localhost:8787/config | jq .engines | length这个命令会返回当前启用的引擎数量正常应该是 9 左右。4.2 Claude Code 内触发搜索打开 Claude Code直接问一个需要联网的问题比如「帮我查一下 FastAPI 性能调优的最新实践」。观察它的工具调用日志如果看到mcp__searxng__searxng_web_search被调用说明 MCP 通道已经生效。我实测的几个场景结果如下中文技术搜索「Python 异步编程最佳实践」Google 返回的技术文档质量最高百度在中文博客覆盖上有优势但广告偏多搜狗的微信公众号文章是独特价值。综合评分 4/5。英文技术搜索「FastAPI performance tuning 2026」Google 表现最佳官方文档、博客、StackOverflow 都能覆盖DuckDuckGo 作为补充也能找到相关内容。综合评分 5/5。中文新闻搜索「AI 人工智能 热点新闻」百度新闻和搜狗新闻在中文媒体覆盖上明显优于 Google这是多引擎聚合的最大价值之一。综合评分 4/5。响应速度方面MCP SearXNG 平均 1 到 3 秒内置 WebSearch 平均 2 到 5 秒。本地部署减少了网络往返速度优势比较明显。4.3 参数传递验证MCP 工具支持传递time_range、language、pageno、min_score等参数。你可以在对话里明确要求「搜索最近一周的内容」Claude Code 会自动把time_range设成week。返回的结果包含标题、URL、摘要Claude Code 能很好地理解和引用。5. 本篇常见错排查5.1 MCP 工具未被调用最常见的情况是 Claude Code 仍然走内置 WebSearch。先检查settings.local.json里的权限是否包含mcp__searxng__searxng_web_search再确认CLAUDE.md里的默认搜索设定是否生效。如果两个都配了还是不行重启 Claude Code 会话。5.2 SearXNG 实例发现失败MCP Server 启动时会调用/config端点发现可用引擎。如果 SearXNG 没启动或端口不对搜索会直接失败。排查命令curl -s http://localhost:8787/config | jq .engines.common.enabled如果这条命令报连接拒绝说明容器没跑起来或者端口映射错了。检查docker-compose.yml里的ports配置和 MCP 配置里的SEARXNG_URL是否一致。5.3 响应时间过长如果每次搜索超过 5 秒大概率是启用的引擎太多。我最初开了 20 多个引擎响应时间直接飙到 5 秒以上。精简到 9 个核心引擎后降到 1 到 3 秒。建议根据实际需求取舍不必追求「全」。5.4 Google 引擎无结果Google 的查询请求由 SearXNG 服务端发出。如果部署环境无法直接访问 Google这个引擎会超时或返回空。可以在 Docker Compose 里给容器指定出口但更简单的做法是先把 Google 权重调低依赖 DuckDuckGo 和百度作为主力。5.5 JSON 格式未生效如果 MCP 返回的结果解析异常检查settings.yml里的formats是否包含json。默认配置只有html不加json的话 MCP Server 拿不到结构化数据。6. 这套方案适合谁以及后续怎么调整体用下来SearXNG 加 Claude Code MCP 的组合在几个维度上表现不错。中文搜索靠多引擎互补覆盖比内置搜索全面英文搜索 Google 引擎质量很高响应速度因为本地部署反而比内置快隐私方面完全本地化搜索数据不出机器。如果你也在用 Claude Code 做日常开发检索这套配置可以直接复制。模型接入这块TaoToken 的 API 通道配置简单Claude Code 填好ANTHROPIC_BASE_URL和 API Key 就能用模型对话和 Coding Plan 都走同一套凭证。API Key 在控制台的 API Keys 页面生成接入文档里有详细的 Claude Code 配置说明。后续还可以继续调优的地方搜索结果排序目前是简单聚合可以按相关性重新排高频搜索词加个缓存层减少重复请求引擎列表也可以根据你的实际使用场景增删比如做前端开发的话可以加上 MDN 相关的垂直搜索源。先把基础链路跑通再按需迭代就行。
