mcp-searxng 客户端配置大全:8 款 MCP 客户端接入配方一次讲清
mcp-searxng 客户端配置大全:8 款 MCP 客户端接入配方一次讲清
mcp-searxng 是一个开源的 MCP 服务器项目,通过 SearXNG 隐私元搜索引擎,为 Claude、Cursor 等 AI 助手提供无需 API 密钥的网络搜索能力。本文是一份 MCP 客户端配置指南,一次性讲清 8 款主流客户端的接入配方:Claude Desktop、Claude Code、Codex CLI、Cursor、VS Code、Windsurf、Cline、OpenCode,帮你 5 分钟完成 SearXNG MCP 服务器的接入。🚀
一、先搞懂:mcp-searxng 是什么?
一句话:mcp-searxng = MCP 客户端 → SearXNG 搜索引擎 之间的桥梁。
MCP 客户端 → mcp-searxng → SearXNG → 各大搜索引擎
它自带 4 个实用工具,接上后即可用:
| 工具 | 用途 |
|---|---|
searxng_web_search |
网络搜索,支持分页、时间范围、语言过滤 |
searxng_search_suggestions |
搜索词自动补全 |
searxng_instance_info |
查看实例支持的分类与引擎 |
web_url_read |
读取网页 / PDF 内容,转为 Markdown |
📌 详细工具参数见 docs/tools.md,完整配置参考见 CONFIGURATION.md。
⚠️ 前提:你需要一个已启用 JSON 搜索的 SearXNG 实例(自建或公共均可)。本项目不负责安装 SearXNG,只负责把你的 MCP 客户端连上去。
二、三种接入模式怎么选?
在配置任何客户端之前,先确定连接模式,这是所有配置的核心分叉点:
| 模式 | 原理 | 依赖 | 适用场景 |
|---|---|---|---|
| NPX / STDIO | 客户端本地拉起 npm 包 | Node.js 22+ | 个人开发机,最省事 ✅ |
| Docker / STDIO | 客户端本地拉起容器 | Docker | 不想装 Node 环境 |
| HTTP | 连接独立运行的服务 | 已部署的 HTTP 服务 | 团队共享同一套搜索服务 |
💡 新手建议:先选 NPX/STDIO 模式,5 分钟就能跑通;团队多人共用再考虑 HTTP。
三、8 款客户端配置配方
以下配方均来自官方文档 docs/client-configurations.md。开始前替换好 3 个占位符:
| 占位符 | 含义 |
|---|---|
https://search.example.com |
你的 SearXNG 实例地址(SEARXNG_URL) |
https://mcp.example.com/mcp |
HTTP 模式下完整的 MCP 端点(注意带 /mcp) |
MCP_SEARXNG_TOKEN |
客户端侧的 Bearer Token 环境变量,需与服务器 MCP_HTTP_AUTH_TOKEN 一致 |
3.1 共享 JSON 配方:一次写好,4 个客户端通用 🔑
Claude Desktop、Cursor、Windsurf、Cline 这 4 个客户端都使用顶层 mcpServers 对象,下面这份 JSON 写好后可以四处复用(NPX 和 Docker 二选一,保留其一即可):
{
"mcpServers": {
"searxng": {
"command": "npx",
"args": ["-y", "mcp-searxng"],
"env": {
"SEARXNG_URL": "https://search.example.com"
}
},
"searxng-docker": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "SEARXNG_URL",
"isokoliuk/mcp-searxng:latest"
],
"env": {
"SEARXNG_URL": "https://search.example.com"
}
}
}
}
⚠️ Docker 配置避坑:千万不要加 -d(后台运行)或 -t(TTY)参数,MCP 客户端需要容器原生的标准输入输出。
Claude Desktop 配置步骤
- 打开 Settings → Developer → Edit Config
- 把上面的 NPX 或 Docker 条目写入
claude_desktop_config.json - 保存并重启 Claude Desktop
远程服务器通过 Claude 的 Connectors UI 添加,不走本地配置文件。
Cursor 配置步骤
将共享 JSON 条目放入:
- 项目级:
.cursor/mcp.json - 全局级:
~/.cursor/mcp.json
Windsurf 配置步骤
将共享 JSON 条目放入 ~/.codeium/windsurf/mcp_config.json。HTTP 模式见下方 Windsurf HTTP 配方。
Cline 配置步骤
- CLI 用户:写入
~/.cline/mcp.json - IDE 用户:打开 MCP Servers → Configure → Configure MCP Servers,把条目加进
mcpServers对象
3.2 Claude Code 配置:命令行一条搞定 ⚡
Claude Code 用 claude mcp 命令管理服务器,支持 STDIO 和 HTTP 两种传输:
# NPX / STDIO 模式
claude mcp add --scope user --env SEARXNG_URL=https://search.example.com --transport stdio searxng -- npx -y mcp-searxng
# Docker / STDIO 模式
claude mcp add --scope user --env SEARXNG_URL=https://search.example.com --transport stdio searxng-docker -- docker run -i --rm -e SEARXNG_URL isokoliuk/mcp-searxng:latest
# HTTP 模式(POSIX shell)
claude mcp add --scope user --transport http searxng-http https://mcp.example.com/mcp --header "Authorization: Bearer ${MCP_SEARXNG_TOKEN}"
# HTTP 模式(PowerShell)
claude mcp add --scope user --transport http searxng-http https://mcp.example.com/mcp --header "Authorization: Bearer $env:MCP_SEARXNG_TOKEN"
验证:运行 claude mcp get searxng,或在会话内输入 /mcp 查看连接状态。
3.3 Codex CLI 配置:TOML 格式 📝
Codex 使用 ~/.codex/config.toml(Windows 为 %USERPROFILE%\.codex\config.toml),TOML 格式跨平台通用:
# NPX / STDIO 模式
[mcp_servers.searxng]
command = "npx"
args = ["-y", "mcp-searxng"]
[mcp_servers.searxng.env]
SEARXNG_URL = "https://search.example.com"
# Docker / STDIO 模式
[mcp_servers.searxng_docker]
command = "docker"
args = ["run", "-i", "--rm", "-e", "SEARXNG_URL", "isokoliuk/mcp-searxng:latest"]
[mcp_servers.searxng_docker.env]
SEARXNG_URL = "https://search.example.com"
# HTTP 模式:Token 从环境变量读取,不写进文件(更安全)
[mcp_servers.searxng_http]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "MCP_SEARXNG_TOKEN"
💡 Codex 会从环境变量读取 Token 而不是从 TOML 文件,这是它的安全设计。用 codex mcp list 查看已配置的服务器。
3.4 VS Code 配置:JSON + 密码输入框 🔒
VS Code 的配置文件结构与上面不同——使用 servers 键,且每个条目要声明 type:
{
"servers": {
"searxng": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-searxng"],
"env": {
"SEARXNG_URL": "https://search.example.com"
}
}
}
}
配置文件位置:工作区级放 .vscode/mcp.json,或运行 MCP: Open User Configuration 打开用户级文件。
HTTP 进阶:VS Code 支持密码输入框,Token 无需明文提交:
{
"inputs": [
{
"id": "searxng-token",
"type": "promptString",
"description": "mcp-searxng bearer token",
"password": true
}
],
"servers": {
"searxng-http": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${input:searxng-token}"
}
}
}
}
保存后运行 MCP: List Servers 启动并检查服务器。
3.5 OpenCode 配置:V2 格式 📦
OpenCode V2 把服务器放在 opencode.json 的 mcp.servers 下(NPX 与 Docker 二选一):
{
"mcp": {
"servers": {
"searxng": {
"type": "local",
"command": ["npx", "-y", "mcp-searxng"],
"environment": {
"SEARXNG_URL": "https://search.example.com"
}
}
}
}
}
HTTP 模式下关闭 OAuth 并直接从环境变量取 Token:
{
"mcp": {
"servers": {
"searxng-http": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:MCP_SEARXNG_TOKEN}"
}
}
}
}
}
用 opencode mcp list 查看服务器列表。
3.6 Windsurf HTTP 配方
Windsurf 支持在 serverUrl 和 headers 中插值环境变量。启动 Windsurf 前先导出 MCP_SEARXNG_TOKEN:
{
"mcpServers": {
"searxng-http": {
"serverUrl": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:MCP_SEARXNG_TOKEN}"
}
}
}
}
然后在 Cascade 的 MCP 设置中重新加载服务器。
3.7 Cline HTTP 配方
Cline 通过 type: "streamableHttp" 支持 Streamable HTTP。注意它目前使用字面量 Token(不支持变量插值),改完后请保护好配置文件、不要提交:
{
"mcpServers": {
"searxng-http": {
"type": "streamableHttp",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer REPLACE_WITH_TOKEN"
},
"disabled": false,
"autoApprove": []
}
}
}
空的 autoApprove 列表表示工具调用仍需正常审批,更安全。
四、HTTP 模式:先起服务器,再接客户端 🌐
HTTP 配方本身不会启动服务。作为运营者,请先按 docs/http-server.md 部署好独立服务,再分享完整的 /mcp 端点:
# 本地快速验证:设置好 SEARXNG_URL 后
MCP_HTTP_PORT=3000 npx -y mcp-searxng
网络服务的关键要点:
- 启用
MCP_HTTP_HARDEN,并设置MCP_HTTP_AUTH_TOKEN - 配置
MCP_HTTP_ALLOWED_ORIGINS与MCP_HTTP_ALLOWED_HOSTS - 静态模式下,客户端的
MCP_SEARXNG_TOKEN必须与服务器MCP_HTTP_AUTH_TOKEN一致 - OAuth 模式(2.2.0+)由外部授权服务器负责登录与发 Token,本服务器只保护资源
五、连接验证:4 步确认配对了 ✅
保存配置后,按顺序检查:
- 重启或重新加载 MCP 服务器
- 检查工具清单,确认出现 4 个工具:
searxng_web_searchsearxng_search_suggestionssearxng_instance_infoweb_url_read
- 调用
searxng_instance_info(加refresh=true可绕过缓存做新鲜探测) - 真实搜索一次:调用
searxng_web_search,参数{"query":"SearXNG"}
⚠️ 常见误区:工具发现成功 ≠ 搜索可用。发现阶段不会真正请求 SearXNG,必须以第 4 步的搜索调用为准。
六、出错排查速查表 🩺
配好后连不上?先看客户端的 MCP 日志,再对照下表:
| 客户端 | 排查入口 |
|---|---|
| Claude Desktop | 改配置后需重启;Settings → Developer 看状态与日志 |
| Claude Code | claude mcp get searxng,会话内 /mcp 重连 |
| Codex CLI | codex mcp list、codex mcp get searxng,看启动/工具报错 |
| Cursor | Customize 里重新加载;Output 面板选 MCP Logs |
| VS Code | MCP: List Servers,选中服务器看 restart / show output |
| Windsurf | Cascade MCP 设置里重载,查看连接/工具报错 |
| Cline | MCP Servers 面板检查;CLI 用 cline config mcp --json |
| OpenCode | opencode mcp list 与会话内 /mcps |
STDIO 三大高频原因:可执行文件缺失、Docker 误加 TTY/分离参数、漏配 SEARXNG_URL。HTTP 高频原因:URL 没带 /mcp 后缀、TLS 问题、Token 不匹配。
更多细节见 docs/troubleshooting.md(含证据收集清单与容器网络问题)。
七、常用文档导航 📚
| 文档 | 说明 |
|---|---|
| README.md | 项目总览与快速开始 |
| docs/client-configurations.md | 本文的完整出处:8 款客户端配方原文 |
| docs/tools.md | 4 个工具的完整参数参考 |
| CONFIGURATION.md | 全部环境变量配置参考 |
| docs/http-server.md | 部署独立 HTTP 服务器指南 |
| docs/self-hosted-searxng.md | 自建 SearXNG 实例 |
| docs/troubleshooting.md | 故障排查与证据收集 |
小结:记住"先选模式、再填配方、最后验证"三步——个人开发用 NPX/STDIO 最快,团队共享用 HTTP 更稳。把本文的配方套进 docs/client-configurations.md,你的 AI 助手今天就拥有隐私搜索超能力 🔍