自建 SearXNG + MCP：给 AI 工具接入可控的网页搜索

AI 编程工具可以通过 MCP 调用搜索，但常见方案往往要求搜索服务的 API Key。若你希望控制自己的搜索入口，可以自建 SearXNG，再用 mcp-searxng 将它接入 MCP 客户端。

这不是“免费且匿名的 Google API”。SearXNG 会把查询转发给你启用的上游搜索引擎；自建的价值在于不必把查询先交给公共 SearXNG 实例运营者，并可控制引擎、日志、网络出口和访问范围。服务器、带宽和代理仍可能产生成本，上游引擎也可能限流或要求 API Key。

本文已按 2026 年 8 月的上游文档修订。旧的 searxng-docker 仓库已经归档；新部署请使用 SearXNG 主仓库提供的 Compose 模板。

架构与前提

AI 客户端（Claude Code / Cursor / VS Code 等）
                 │ MCP（stdio）
                 ▼
         mcp-searxng（本机 Node.js 进程）
                 │ HTTP + JSON
                 ▼
       SearXNG（由你控制的实例）
                 │
                 ▼
       你启用的上游搜索引擎

你需要 Docker Compose、Node.js 20 或更高版本，以及一个支持 stdio MCP 的客户端。下文假设 SearXNG 与 MCP 客户端运行在同一台机器；如果 SearXNG 位于远程服务器，请将示例中的 http://localhost:8080 替换为该实例的 HTTPS 地址。

第一步：用官方 Compose 模板部署 SearXNG

创建目录并下载当前模板：

mkdir -p searxng/core-config
cd searxng

curl -fsSLO https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
cp .env.example .env

请先阅读生成的 .env，只修改其中已有且确实需要的变量。模板会随版本演进，不应再沿用旧教程里的 SEARXNG_HOSTNAME、Caddyfile 或 Redis 容器配置。

在 core-config/settings.yml 中放入最小配置：

use_default_settings: true

server:
  # 用 openssl rand -hex 32 生成，绝不要提交到仓库
  secret_key: "替换为随机字符串"
  # 个人本机实例可关闭；公开服务应启用 limiter 并配好 Valkey
  limiter: false
  # 非必要不代理图片，减少请求和资源消耗
  image_proxy: false

search:
  default_lang: "zh-CN"
  formats:
    - html
    - json

json 是本方案的关键：mcp-searxng 通过 SearXNG 的 JSON 搜索 API 查询结果。不要把随机 secret_key 写成示例值，也不要将配置文件提交到公开仓库。

启动服务：

docker compose up -d
docker compose ps

官方 Compose 示例默认会把服务发布到 8080。先在浏览器打开 http://localhost:8080，再验证 JSON API：

curl 'http://localhost:8080/search?q=hello+world&format=json'

若返回 403，通常是 search.formats 未包含 json、配置文件未被挂载，或 YAML 缩进有误。修改后重启服务：

docker compose restart core

引擎、API Key 与限流

use_default_settings: true 会使用 SearXNG 的默认引擎集合。先用默认配置验证，再按需调整 engines，不要从教程复制一份过时的完整引擎列表。

特别注意：并非所有引擎都免 Key。例如 SearXNG 的 Brave API 引擎需要 api_key；不要在没有 Key 的情况下启用它，更不能据此宣称整套方案“不需要任何 API Key”。直接抓取搜索结果的引擎也可能触发验证码、429 或临时禁用。

限制 SearXNG 到上游引擎的连接，应使用 outgoing 配置，而不是 server.max_connections：

outgoing:
  request_timeout: 5.0
  pool_connections: 20
  pool_maxsize: 5

上游访问需要经由代理时，也应配置在 SearXNG 的 outgoing.proxies，因为真正请求 Google、Bing 等的是 SearXNG，不是 MCP 进程。

outgoing:
  proxies:
    all://:
      - http://proxy.example:8080

不要把代理地址、密码或 API Key 写入 Git。公开部署还应设置 HTTPS、反向代理、访问认证和限流；仅打开 JSON API 并不等于访问控制。

第二步：配置 mcp-searxng

mcp-searxng 是独立的 Node.js MCP Server。最简单的方式是让客户端通过 npx 启动：

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}

首次运行会下载包。生产或团队环境建议固定已验证的包版本，而不是长期使用浮动的最新版。

SearXNG 由反向代理保护为 HTTP Basic Auth 时，可把已百分号编码的凭据嵌入 SEARXNG_URL：

{
  "env": {
    "SEARXNG_URL": "https://username:password@search.example.com"
  }
}

不要把包含凭据的 JSON 提交进版本库。AUTH_USERNAME 和 AUTH_PASSWORD 仍是兼容旧配置的后备变量，但 URL 内凭据更适合多实例分别认证。

配置多个可互换实例时可用分号分隔；默认按顺序故障转移：

{
  "env": {
    "SEARXNG_URL": "https://one.example.com;https://two.example.com"
  }
}

只有这些实例确实提供相同能力时，才使用 SEARXNG_FANOUT=true 并行搜索和合并结果；否则不同索引、语言或引擎配置会让结果难以解释。

第三步：接入客户端

Claude Code

claude mcp add searxng -s user -e SEARXNG_URL=http://localhost:8080 -- npx -y mcp-searxng

-s user 使配置对当前用户的项目生效。执行 claude mcp list 检查是否已被识别。

Cursor 与 Claude Desktop

Cursor 使用项目目录下的 .cursor/mcp.json；Claude Desktop 使用 claude_desktop_config.json。两者的 stdio 配置均可使用上一节的 mcpServers JSON。保存后重启客户端，并在 MCP 面板确认服务已连接。

VS Code

在工作区新建或编辑 .vscode/mcp.json，但 VS Code 的顶层键是 servers：

{
  "servers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}

Cline 有自己的 MCP 配置入口，不应假定会读取 .vscode/mcp.json。请在其设置中添加同一份 stdio Server 定义。

能力与验证方式

当前 mcp-searxng 暴露的核心工具是：

searxng_web_search：网页搜索，可传 categories、engines、language、time_range、num_results 等参数。
searxng_search_suggestions：通过 SearXNG 获取搜索建议。
searxng_instance_info：查看实例实际可用的分类、引擎与默认值。
web_url_read：抓取公开 URL 并转为适合阅读的文本/Markdown。

新闻、图片、视频、学术搜索不是独立的 MCP 工具名；应由 searxng_web_search 的 categories 和实例中真实启用的引擎决定。配置完成后，先调用 searxng_instance_info，再发起一次普通网页搜索，确认返回的引擎和结果符合预期。

网页读取、FlareSolverr 与安全边界

web_url_read 会把外部网页内容带回模型上下文。网页内容不可信：它可能包含提示词注入、虚假指令、敏感信息诱导或恶意链接。把搜索结果当作资料，而不是系统指令；不要让模型因网页文字泄露密钥、绕过审批，或执行未经确认的命令。

对于 JavaScript 重、挑战页或验证码页，可以选择部署受信任的 FlareSolverr，并为 MCP 进程设置正确变量：

{
  "env": {
    "SEARXNG_URL": "http://localhost:8080",
    "FLARESOLVERR_URL": "http://flaresolverr:8191"
  }
}

它不是保证绕过所有反爬的工具。配置后，待读取 URL 会被交给该浏览器服务处理；因此应将其置于私有容器网络、不要映射 8191 到公网，并限制它访问内网和云元数据地址。没有明确的合规授权时，不要用它规避网站的访问控制或服务条款。

总结

这套方案适合需要可控搜索入口的个人或小团队：使用官方 SearXNG Compose 模板，开启 JSON 格式，再将 mcp-searxng 作为 stdio MCP Server 接入客户端。它减少了对公共聚合服务的依赖，但不会消除上游搜索引擎、基础设施成本、访问条款、隐私和提示词注入风险。

上线前请至少检查：实例未意外暴露公网；JSON API 的访问范围符合预期；secret_key、认证信息和代理凭据未提交；启用的搜索引擎确实可用；以及客户端仅信任来自可信来源的 MCP Server。