mcp-searxng 客户端配置大全:8 款 MCP 客户端接入配方一次讲清

原创2026-10-12 15:16:441,885 阅读

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 配置步骤

  1. 打开 Settings → Developer → Edit Config
  2. 把上面的 NPX 或 Docker 条目写入 claude_desktop_config.json
  3. 保存并重启 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 步确认配对了 ✅

保存配置后,按顺序检查:

  1. 重启或重新加载 MCP 服务器
  2. 检查工具清单,确认出现 4 个工具:
    • searxng_web_search
    • searxng_search_suggestions
    • searxng_instance_info
    • web_url_read
  3. 调用 searxng_instance_info(加 refresh=true 可绕过缓存做新鲜探测)
  4. 真实搜索一次:调用 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 助手今天就拥有隐私搜索超能力 🔍

登录后查看全文
mcp-searxng