mcp-searxng 配 TaoToken：Agent 搜索 MCP 服务 settings.json 骨架与连通验证

1. 为什么 Agent 需要一个搜索 MCP 服务如果你正在用 Claude Code、Cursor、Cline 这类支持 MCP 协议的 Agent 工具大概率遇到过同一个尴尬模型知识停在训练截止日期问它最新的库版本、某个报错的社区解法、某个 API 的字段变更它要么编要么直接说不知道。Agent 本身有推理和写代码的能力但它没有眼睛去看现在的互联网。MCPModel Context Protocol就是解决这个问题的标准接口。它把外部能力包装成 Agent 可以调用的工具搜索就是其中最刚需的一类。而 mcp-searxng 这个包做的事情很直接把自建的 SearXNG 元搜索引擎包装成一个 MCP 服务让 Agent 通过标准协议发起网页搜索拿到结构化的标题、链接、摘要。SearXNG 本身是一个开源的元搜索引擎它聚合多个搜索源的结果不追踪用户支持 JSON 输出。这一点对 Agent 很关键——Agent 需要的是机器可读的 JSON不是给人看的 HTML 页面。mcp-searxng 就是架在 SearXNG 和 Agent 之间的那层适配器。这篇面向的是本地已经装好 Node/npm 的开发者。目标很明确一次配置跑通 Agent 搜索链路。我会给出 settings.json 里 mcp-searxng 的完整骨架、TaoToken 统一 Key 和 API 通道该填在哪、以及启动后怎么用一次真实搜索请求验证连通。踩过的坑我也会标出来省得你在配置格式上反复试错。2. 前置准备SearXNG 实例与 TaoToken 通道2.1 先把 SearXNG 跑起来mcp-searxng 自己不提供搜索能力它只是个转发层真正的搜索由 SearXNG 实例完成。所以第一步是有一个能返回 JSON 的 SearXNG。用 Docker 起一个最省事docker run --name searxng -d \ -p 8888:8080 \ -v ./config/:/etc/searxng/ \ -v ./data/:/var/cache/searxng/ \ docker.io/searxng/searxng:latest起来之后访问http://localhost:8888能看到搜索页就说明容器正常。但默认配置下 JSON 格式是关掉的Agent 拿不到结构化结果必须改配置。在挂载出来的config/settings.yml里重点确认这几项use_default_settings: engines: keep_only: - bing - baidu - 360search - sogou - quark - stackoverflow - github server: secret_key: 换成你自己的随机字符串 bind_address: 0.0.0.0 limiter: false search: formats: - html - json language: zh-CN locale: zhsearch.formats里必须包含json这是 mcp-searxng 能工作的前提。limiter: false是为了避免本地调试时被限流挡住。bind_address: 0.0.0.0保证容器端口映射生效。改完重启容器docker restart searxng验证 JSON 是否开启直接 curl 一下curl http://localhost:8888/search?qtestformatjson返回一段 JSON 数组就对了。如果返回 HTML 或者 403说明formats没生效或者 limiter 还开着回去检查配置。2.2 TaoToken 统一 Key 与 API 通道Agent 侧要调用模型就需要一个稳定的 API 通道。TaoToken 在这里的角色是统一入口一个 Key 走通模型对话、编码计划、以及各类 MCP 相关的调用不用在多个平台之间来回切换配置。你需要准备两样东西一是 API Key。到控制台创建地址是https://taotoken.net/console创建完在 API Keys 页面能看到形如sk-开头的一串。这个 Key 后面要填进 Agent 的模型配置里。二是 API 通道地址。TaoToken 的 API 端点是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base_url 使用。很多工具要求 base_url 以/v1结尾或者不带具体看工具文档但根地址就是它。如果你用的是 Claude Code 这类需要 Anthropic 兼容协议的工具接入文档在https://taotoken.net/doc里面有不同客户端的填写示例。模型对话的在线体验入口在https://taotoken.net/models配置前可以先在那里确认 Key 能用。注意API Key 属于敏感凭证不要提交到 Git 仓库也不要写进会分享出去的配置文件。本地开发建议用环境变量或者单独的本地配置文件。3. settings.json 完整骨架与字段填写3.1 安装 mcp-searxng全局装npm install -g mcp-searxng装完确认一下命令可用which mcp-searxng能输出路径就说明装好了。如果你用 npx 方式调用也可以不全局装但全局装的好处是配置里路径固定不容易因为工作目录变化找不到。3.2 MCP 服务配置骨架不同 Agent 工具的 MCP 配置文件位置不一样但结构大同小异。Claude Code 用的是~/.claude/settings.json或者项目级的.mcp.jsonCursor 用的是~/.cursor/mcp.jsonCline 在 VS Code 设置里。下面这份骨架以通用的mcpServers结构为准你按自己工具的位置放。{ mcpServers: { mcp-searxng: { command: mcp-searxng, args: [], env: { SEARXNG_URL: http://localhost:8888, SEARXNG_TIMEOUT: 15000, TAOTOKEN_API_KEY: sk-你的TaoToken密钥, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }逐字段说明command是启动 MCP 服务的可执行命令。全局安装后直接写mcp-searxng即可。如果你用 npx这里写npx然后在args里写[-y, mcp-searxng]。args是传给命令的参数。直接调用可执行文件时留空数组。env是环境变量这是配置的核心。SEARXNG_URL指向你本地或远程的 SearXNG 实例地址端口要和 Docker 映射的一致。SEARXNG_TIMEOUT是搜索请求超时单位毫秒设 15000 比较稳网络慢的时候不至于直接失败。TAOTOKEN_API_KEY填你在控制台创建的 Key。TAOTOKEN_BASE_URL填https://taotoken.net/api。这两个字段的作用是让 MCP 服务在需要模型侧能力时走统一通道而不是各自散落配置。提示如果你的工具不支持在 MCP 配置里直接写 env可以把这些变量写进 shell 的 profile 文件MCP 服务启动时会继承。但要注意别把 Key 明文提交到版本控制。3.3 配置格式的三个易错点第一JSON 不允许尾随逗号。args: [],后面如果还有字段没问题但最后一个字段后面加逗号会直接解析失败。很多工具报错信息很模糊只说配置无效实际就是逗号问题。第二路径要用绝对路径或者确保在 PATH 里。command写mcp-searxng依赖 PATH如果你在 GUI 工具里启动PATH 可能和终端不一样找不到命令。稳妥做法是写绝对路径比如/usr/local/bin/mcp-searxng用which mcp-searxng查出来填进去。第三SEARXNG_URL不要带尾斜杠。写http://localhost:8888而不是http://localhost:8888/有些 HTTP 客户端拼接路径时会把双斜杠当异常处理。4. 启动与一次搜索请求的连通验证4.1 重启 Agent 让配置生效改完配置文件后必须完全重启 Agent 工具不是刷新窗口。MCP 服务是在工具启动时拉起的子进程配置变更不会热加载。重启后在 Agent 里查看 MCP 服务列表应该能看到mcp-searxng处于 connected 状态。如果显示 failed 或者根本没出现先看工具的 MCP 日志通常在设置里的 MCP 面板或者日志文件里。4.2 用一次真实搜索验证链路最直接的验证方式是在 Agent 对话里让它搜索一个具体问题。比如帮我搜索一下 mcp-searxng 的最新版本号给出信息来源链接Agent 会调用 mcp-searxng 的搜索工具底层向你的 SearXNG 实例发请求SearXNG 聚合结果后返回 JSONMCP 服务把结果整理给模型模型再组织成回答。如果链路通了你会看到 Agent 返回带链接的结果而不是凭空编造。这一步成功说明 SearXNG、mcp-searxng、Agent 三者之间的连接全部正常。4.3 绕过 Agent 直接测 MCP 服务有时候 Agent 侧报错信息不清晰可以单独测 MCP 服务本身。mcp-searxng 支持 stdio 模式你可以手动发一条 JSON-RPC 消息看它响应。先确认 SearXNG 的 JSON 接口正常curl -s http://localhost:8888/search?qnodejsformatjson | head -c 500返回 JSON 片段说明 SearXNG 没问题。如果这里就失败问题在 SearXNG 配置不在 MCP 层。再确认 mcp-searxng 能启动SEARXNG_URLhttp://localhost:8888 mcp-searxng --help能打印帮助信息说明命令本身可用环境变量也能被读取。如果这一步报错多半是 npm 全局安装的 bin 没进 PATH或者 Node 版本太低。4.4 成功结果的判断标准一次成功的搜索请求返回结果应该包含这几个特征有明确的标题、有可点击的 URL、有摘要文本、结果条数在合理范围通常 5 到 20 条。如果返回空数组说明 SearXNG 的引擎配置有问题可能keep_only里列的引擎都被禁用了或者网络请求超时。如果返回的结果里 URL 全是 SearXNG 自己的域名说明image_proxy或者结果代理配置有问题需要检查settings.yml里的相关项。5. 本篇常见错误排查5.1 MCP 服务启动失败command not found现象是 Agent 的 MCP 面板显示服务无法启动日志里有spawn mcp-searxng ENOENT。原因是 GUI 工具的 PATH 不包含 npm 全局 bin 目录。解决方法是把command改成绝对路径which mcp-searxng # 输出比如 /usr/local/bin/mcp-searxng把输出路径填进配置的command字段。Windows 上路径类似C:\Users\你的用户名\AppData\Roaming\npm\mcp-searxng.cmd注意要带.cmd后缀。5.2 搜索返回空结果SearXNG 起来了MCP 也连上了但搜索返回空数组。最常见的原因是settings.yml里keep_only列出的引擎全部不可用或者formats里没开json。排查顺序先 curl 直接测 SearXNG 的 JSON 接口确认它自己能返回结果。如果 curl 也返回空问题在 SearXNG 的引擎配置检查engines段里各引擎的disabled是否为false。如果 curl 正常但 MCP 返回空检查SEARXNG_URL是否写错特别是端口。5.3 请求超时现象是 Agent 等很久然后报超时。SearXNG 聚合多个引擎某些引擎响应慢会拖累整体。两个调整方向一是把SEARXNG_TIMEOUT调大比如 30000二是在settings.yml里给慢引擎单独设timeout或者干脆从keep_only里去掉不稳定的引擎。outgoing.request_timeout和outgoing.max_request_timeout也值得调前者是单个请求超时后者是整体上限。5.4 JSON 解析报错Agent 日志里出现 JSON parse error通常是 MCP 服务返回了非 JSON 内容。根源往往是 SearXNG 返回了 HTML 错误页而不是 JSON。检查search.formats是否包含json以及limiter是否关闭。如果 SearXNG 前面还有反向代理确认代理没有改写响应内容类型。5.5 Key 无效或 401如果 Agent 在调用模型侧能力时报 401检查TAOTOKEN_API_KEY是否填对有没有多余空格。Key 创建后如果被删除或轮换旧 Key 会失效需要重新生成并更新配置。TAOTOKEN_BASE_URL确认是https://taotoken.net/api不要多加/v1或者尾斜杠除非你用的工具文档明确要求。6. 把搜索链路接进你的 Agent 工作流配置跑通只是第一步真正有价值的是把它用起来。几个实际场景你可以直接试查最新版本和变更日志。让 Agent 搜索某个 npm 包的最新版本它会去 GitHub releases 或者 npm 页面拿真实数据而不是靠训练时的记忆。排查报错。把报错信息丢给 Agent让它搜索社区讨论往往能直接找到 Stack Overflow 或者 GitHub issue 里的解法。核对 API 字段。写代码时不确定某个接口的字段名让 Agent 搜官方文档比翻本地缓存靠谱。如果你打算长期在编码和 Agent 场景里用TaoToken 的 Coding Plan 值得看一下入口在https://taotoken.net/coding-plan适合需要稳定通道和统一 Key 管理的开发者。模型对话的在线验证在https://taotoken.net/models接入文档在https://taotoken.net/docAPI Key 管理在https://taotoken.net/api-keys。配置这件事一次填对省下的是后面反复调试的时间。骨架给你了字段含义也标了剩下的就是复制、改路径、重启、验证。搜索链路通了之后你的 Agent 才算真正长出了看互联网的眼睛。