🔍 SearXNG MCP 服务器

为 AI 助手提供尊重隐私的网页搜索——通过由操作者控制或可信的 SearXNG 实例，与 Claude、Cursor 等工具配合使用。

一个集成 SearXNG API 的 MCP 服务器，为 AI 助手提供网页搜索能力。

✨ 已收录于 GitHub MCP Registry。

快速开始

在您的 MCP 客户端配置（例如 claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

将 YOUR_SEARXNG_INSTANCE_URL 替换为您的 SearXNG 实例 URL（例如 https://searxng.example.com）。您也可以提供可互换的副本，以分号分隔的列表形式给出，例如 https://one.example.com;https://two.example.com。

有关经过验证的 Claude Desktop、Claude Code、Codex CLI、Cursor、VS Code、Windsurf、 Cline 和 OpenCode 配置方案，请参阅 MCP 客户端配置手册。

有关一种有界、与客户端无关的搜索、检查来源、交叉验证 声明并引用证据的方法，请参阅 以证据为中心的研究工作流。

有关实测的 MCP 进程 CPU 和内存起始参考值，请参阅 实测部署配置。

Related MCP server: SearXNG MCP Server

功能特性

• 网页搜索：支持通用、新闻和文章查询，提供分页、时间范围/语言/安全搜索过滤器、相关性过滤（min_score），以及按调用选择（response_format）或使用操作者默认值（SEARXNG_DEFAULT_RESPONSE_FORMAT）的格式化文本或原始 JSON 输出。

• 实例故障转移与扇出：在 SEARXNG_URL 中配置可互换的 SearXNG 副本；默认情况下搜索按顺序进行故障转移，或使用 SEARXNG_FANOUT 并行查询所有健康副本并合并结果。

• 直接答案与元数据：文本结果在结果列表之前展示 SearXNG 的答案、更正、建议和信息框。

• 搜索建议：通过 SearXNG 的 /autocompleter 端点实现查询自动补全。

• 实例能力发现：从 /config 检查已配置的分类、引擎、默认值、区域设置和插件。

• URL 内容读取：支持内容类型感知的 Markdown 转换，包括有界的 PDF 文本提取，并提供分页、章节过滤、段落范围和标题提取功能。

• 浏览器求解器支持：对于每个通过静态 URL 验证和 HEAD 大小预检的未缓存 URL，可选择从 FlareSolverr、Byparr 或两者获取浏览器会话，然后将返回的用户代理和限定范围的 cookie 通过有界的 URL 读取器重放。在双提供者模式下，FlareSolverr 始终是主提供者，仅当主提供者繁忙或暂时不可用时才尝试 Byparr。FlareSolverr 3.5.0 和 Byparr 2.1.0 已于 2026-07-30 验证。

• 智能缓存：搜索结果和 URL 内容均在内存中缓存，具有可配置的 TTL 和最不常用（LFU）淘汰策略，减少冗余请求。

• SSRF 防护：web_url_read 默认在所有传输模式下阻止私有/内部 URL 和重定向。

• HTTP 传输：可选的 MCP SDK v2 Streamable HTTP 模式，具有可选加固、速率限制和有界无状态兼容性，适用于无服务器或水平扩展部署。现代 2026-07-28 请求和保留的旧版客户端共享相同的工具和资源表面。

• HTML 回退：对于拒绝 format=json 的公共实例，可选择从 HTML 页面解析结果。

• 精简工具模式：为上下文窗口较小的本地模型提供最小化工具模式。

• 代理支持：为搜索和 URL 读取器流量提供全局或按工具的 HTTP/HTTPS 代理。

经过验证的 linux/amd64 镜像来自多架构清单 ghcr.io/flaresolverr/flaresolverr:v3.5.0@sha256:139dfee1c6f89249c8d665d1333a42e8ec74ec0a86bc6bb1c8461e10d3a66a47 和 ghcr.io/thephaseless/byparr:2.1.0@sha256:01a46a2865d9a6db5eb8ead04ec0dd33b8fbe233e8565ae70b50d4cc0af4cfb0。 客户端取消会立即停止本地工作，但远程浏览器可能会在 HTTP 客户端断开连接后继续运行，直到其配置的提供者超时。请参阅浏览器求解器验证。

为什么选择 mcp-searxng？

截至 2026-07-29，以下能力对比反映了官方 Brave MCP、 Exa MCP 和 Firecrawl MCP 项目。 “分页”指暴露了页面或偏移量控制。“自托管”指搜索服务可以在您的控制下运行。“免费 / 无需 API 密钥”指此 MCP 服务器不需要付费的搜索供应商 API 密钥；您仍需自行运营或选择底层的 SearXNG 实例。

隐私取决于 SearXNG 的部署方式。由操作者控制的实例可以避免信任第三方搜索运营者，而公共实例会收到查询并可能记录日志。SearXNG 和此 MCP 集成本身并不提供匿名性。

工作原理

mcp-searxng 是一个独立的 MCP 服务器——一个单独的 Node.js 进程，您的 AI 助手通过它连接以进行网页搜索。它通过 HTTP JSON API 查询一个 SearXNG 实例，或一个以分号分隔的可互换 SearXNG 副本列表。

不是 SearXNG 插件： 此项目不能作为原生 SearXNG 插件安装。通过设置 SEARXNG_URL，将其指向任何现有的 SearXNG 实例或可互换的副本列表即可。

AI Assistant (e.g. Claude)
        │  MCP protocol
        ▼
  mcp-searxng  (this project — Node.js process)
        │  HTTP JSON API  (SEARXNG_URL)
        ▼
  SearXNG instance(s)

有关 SearXNG 的部署、配置和故障排除，请参阅 使用 mcp-searxng 运营自托管 SearXNG。

工具

• searxng_web_search

  • 执行带分页的网页搜索

  • 输入：

    • query（字符串）：搜索查询。此字符串会传递给外部搜索服务。

    • pageno（数字，可选）：搜索页码，从 1 开始（默认 1）

    • time_range（字符串，可选）：按时间范围筛选结果 - 可选值："day"、"week"、"month"、"year"（默认：无）

    • language（字符串，可选）：结果的语言代码（例如 "en"、"fr"、"de"）或 "all"（默认："all"）

    • safesearch（字符串枚举，可选）：安全搜索过滤级别，可选值 "0"（无）、"1"（中等）或 "2"（严格）。为向后兼容，仍接受旧式数字值 0、1 和 2。（默认：实例设置）

    • min_score（数字，可选）：最低相关度分数，范围 0.0 到 1.0。低于此分数的结果将被过滤掉。

    • num_results（数字，可选）：返回的最大结果数，范围 1 到 20。SEARXNG_MAX_RESULTS 作为操作员上限。

    • categories（字符串，可选）：逗号分隔的 SearXNG 类别（例如 "news"、"it,science"）。实时 /config 能力会跨可达实例聚合；建议使用 searxng_instance_info 的 categories.common 以获得一致的多实例结果。已知值会被修剪并忽略大小写进行规范化；未知值会按修剪后的原样转发，以便 SearXNG 忽略或采纳。如果 /config 不可用，则按原样转发并发出警告。如果省略，每个实例使用其服务器端默认值。

    • engines（字符串，可选）：逗号分隔的 SearXNG 引擎名称（例如 "google,bing,ddg"、"semantic scholar"）。实时 /config 能力会跨可达实例聚合；建议使用 searxng_instance_info 的 engines.common.enabled 以获得一致的多实例结果。已知值会被修剪并忽略大小写进行规范化，包括默认禁用的引擎；未知值会按修剪后的原样转发，以便 SearXNG 忽略或采纳。如果 /config 不可用，则按原样转发并发出警告。如果省略，每个实例使用其服务器端默认值。

    • response_format（字符串，可选）：响应格式，"text" 表示格式化的代理可读输出，"json" 表示带有过滤/切片 results 的原始 SearXNG JSON。如果省略，则应用 SEARXNG_DEFAULT_RESPONSE_FORMAT；如果未设置或无效，则使用 text。显式的 response_format 始终优先。

    • result_detail（字符串，可选）："full"（默认）保留 SearXNG 元数据、警告、来源、答案、信息框、更正和建议。"compact" 仅返回每个结果的标题、URL 和描述/内容片段；紧凑 JSON 恰好使用 title、url 和 content 键。当这些研究信号重要时，请使用完整模式。

    • 显式发送或自动注入 response_format=text 的客户端将继续覆盖操作员默认值。如果省略调用在配置 JSON 后仍返回文本，请检查 MCP 客户端发出的参数。

  迁移：紧凑文本每个结果恰好三行，没有缓存注释或前言。更新期望相关度分数或搜索元数据的行解析器，以请求 result_detail="full"（或接受紧凑的三行记录）。

  紧凑模式故意抑制警告、来源和所有其他搜索信号。完整文本可能按固定顺序添加有效的可选行：分数、引擎、类别、发布日期、缩略图、图片来源；无效的可选元数据将被省略。文本字段规范化为单行。SEARXNG_MAX_RESULT_CHARS 在紧凑和完整文本/JSON 响应中截断结果内容，包括对已设置该变量的现有用户的完整 JSON；紧凑文本在应用上限前规范化行分隔符，而 JSON 则对原始字符串值设置上限。

  使用 SEARXNG_LITE_TOOLS=true 时，Lite 模式保持仅查询，但显式提供的可选覆盖（如 response_format 和 result_detail）仍会被验证并采纳。

• searxng_search_suggestions

  • 获取自动补全建议以优化搜索查询

  • 输入：

    • query（字符串）：要自动补全的部分或完整查询。

    • language（字符串，可选）：建议的语言代码（例如 "en"、"fr"、"de"）或 "all"（默认："all"）

• searxng_instance_info

  • 发现从可达的已配置 SearXNG 实例聚合的类别，可选包含引擎名称，并检查主可达实例的默认值、区域设置和插件。类别（以及请求时的引擎）报告 common 值（存在于每个可达实例）和 available 值（至少存在于一个可达实例）。

  • 输入：

    • includeEngines（布尔值，可选）：在响应中包含已启用的引擎名称。（默认：false）

    • includeDisabled（布尔值，可选）：当 includeEngines 为 true 时，包含已禁用的引擎名称。（默认：false）

    • category（字符串，可选）：将类别和引擎过滤为单个类别名称。

    • refresh（布尔值，可选）：绕过进程缓存并获取新的 /config 数据。（默认：false）

• web_url_read

  • 以 markdown 格式读取 URL 内容，支持内容类型感知处理和高级提取选项

  • 支持的可读内容：

    • HTML（text/html、application/xhtml+xml）转换为 markdown

    • JSON（application/json、*+json）在围栏块中漂亮打印

    • 纯文本、YAML、TOML、XML 和其他安全显式 text/* 响应以可读的围栏文本返回

    • PDF（application/pdf）文本在资源受限的工作进程中提取，适用于最多 500 页的文档

    • 缺失或通用内容类型在现有大小上限下读取；非二进制主体继续通过 HTML 到 markdown 路径以保持兼容性

  • PDF 输入和提取的文本各自以 URL_READ_MAX_CONTENT_LENGTH_BYTES 和 16 MiB 中的较小值为上限。不支持 OCR，扫描/纯图像或受密码保护的 PDF 返回简短说明。

  • 声明为 PDF 的响应必须以 %PDF- 签名开头；不匹配通常表示中间页或错误页使用了错误的内容类型。

  • PDF 解析在响应体下载后有单独的 30 秒工作进程预算。在直接路径上，网络获取和解析最多占用配置的获取预算加 30 秒；配置的浏览器求解器预检和获取时间额外计算。

  • 每个 MCP 进程最多并发执行两次 PDF 提取。没有队列；额外的并发读取返回忙碌消息，可重试。

  • 其他二进制、媒体、归档和八位字节流下载被有意拒绝，并返回简短提示，而不是返回原始字节

  • 当配置了 FLARESOLVERR_URL 或 BYPARR_URL 时，未缓存的 URL 在 mcp-searxng 尝试浏览器会话获取之前会经过验证和 HEAD 大小预检。两者都设置时，先尝试 FlareSolverr，仅在忙碌槽、网络/超时失败、HTTP 408/429/5xx 或格式错误/过大响应后尝试 Byparr。持久性提供程序 4xx、取消、解决方案主机验证失败和已解决的非 2xx 目标状态会停止链。如果每个配置的提供程序都忙碌或不可用，则执行一次未缓存的直接获取。每个尝试的提供程序都会收到原始目标 URL；挑战成功不保证。

  • 在默认限制下，双提供程序模式在初始 HEAD 预检、两次求解器尝试（包括响应宽限）和最终直接获取之间具有 150 秒的加性最大值。

  • 输入：

    • url（字符串）：要获取和处理的 URL

    • startChar（数字，可选）：内容提取的起始字符位置（默认：0）

    • maxLength（数字，可选）：返回的最大字符数

    • section（字符串，可选）：提取特定标题下的内容（搜索标题文本）

    • paragraphRange（字符串，可选）：返回特定的段落范围（例如 '1-5'、'3'、'10-'）

    • readHeadings（布尔值，可选）：仅返回标题列表而不是完整内容

安装

需要 Node.js 22 或更高版本。

npm install -g mcp-searxng

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

预构建镜像：

docker pull isokoliuk/mcp-searxng:latest

镜像签名可使用 Cosign 验证 — 参见 SECURITY.md 中的说明。

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

要传递额外的环境变量，请将 -e VAR_NAME 添加到 args，并将变量添加到 env。 对于浏览器求解器集成，传递 FLARESOLVERR_URL、BYPARR_URL 或两者， 并确保配置的服务可从该容器访问。双模式具有 固定的 FlareSolverr 优先顺序，没有自动反向故障转移。参见 URL 读取器控制 了解完整 行为和 Docker Compose 示例。

本地构建：

docker build -t mcp-searxng:latest -f Dockerfile .

使用上述相同配置，将 isokoliuk/mcp-searxng:latest 替换为 mcp-searxng:latest。

docker-compose.yml：

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=${SEARXNG_URL:?Set SEARXNG_URL in the environment}
      # Add optional variables as needed — see CONFIGURATION.md

跟踪的 Compose 文件有意仅支持 STDIO，不发布网络端口；MCP 客户端使用绝对 Compose 文件路径和 docker compose run --rm -T 启动它，而不是 docker compose up。-T 标志防止伪 TTY 分配，使 MCP JSON-RPC 保持在原始标准输入和输出上。除非 MCP 客户端提供 SEARXNG_URL，否则 Compose 在启动前失败。

MCP 客户端配置：

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/docker-compose.yml",
        "run", "--rm", "-T", "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

如果您之前将跟踪的文件用作端口 8080 上的 HTTP 服务，请将 HTTP 设置放在未跟踪的 docker-compose.override.yml 中：

services:
  mcp-searxng:
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MCP_HTTP_PORT=8080
      - MCP_HTTP_HOST=0.0.0.0

这里 0.0.0.0 是容器端绑定地址；主机端端口保持仅回环。此覆盖没有身份验证，仅是临时的单主机迁移路径。在添加同置容器或将服务暴露到本地机器之外之前，请遵循加固的部署指南。

默认情况下，服务器使用 STDIO，由您的 MCP 客户端启动。要使用 HTTP，请将 mcp-searxng 作为独立进程运行，并设置 MCP_HTTP_PORT。在此模式下，它通过 HTTP 提供 MCP 协议，不处理 STDIO，因此您的客户端通过 URL 连接，而不是生成它。

启动服务器：

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng

或使用 Docker（绑定到所有接口，以便端口可从主机访问）：

docker run --rm -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e MCP_HTTP_PORT=3000 -e MCP_HTTP_HOST=0.0.0.0 \
  -e SEARXNG_URL=http://host.docker.internal:8080 \
  isokoliuk/mcp-searxng:latest

--add-host 映射允许容器通过 host.docker.internal 访问主机上的 SearXNG 实例；在 Docker Desktop 上会自动解析，但在原生 Linux 上需要此标志。如果实例在其他地方运行，请将 SEARXNG_URL 指向您的实际实例。

将支持 HTTP 的 MCP 客户端连接到 /mcp 端点，通过 URL：

{
  "mcpServers": {
    "searxng-http": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

协议支持： HTTP 和 STDIO 提供现代 MCP 2026-07-28 以及保留的旧版修订 2025-11-25、2025-06-18、2025-03-26、2024-11-05 和 2024-10-07。现代 HTTP 是无会话的 POST /mcp；旧版 HTTP 默认保持有状态（POST/GET/DELETE /mcp）或使用现有的仅 POST 无状态模式。

端点： 现代 POST /mcp；旧版在有状态默认下为 POST/GET/DELETE /mcp，或在无状态模式下仅 POST /mcp；GET /health。

对于旧版 HTTP 客户端，有状态会话仍是默认。当部署无法在请求之间保留内存中的旧版会话时，设置 MCP_HTTP_STATELESS=true。现代 HTTP 无论该设置如何都保持无会话。每个无状态 POST 都会创建全新的 MCP 服务器和传输，忽略任何传入的会话 ID，并在同一 POST 内返回协商的 JSON 或 SSE 流。无状态模式仅支持 POST：GET /mcp 和 DELETE /mcp 返回 HTTP 405，并带有 Allow: POST，且不保留跨请求订阅、可恢复性或服务器到客户端的通知。

无状态请求受全局和每客户端 IP 的在途限制以及请求生命周期的约束。有关默认值、过载和超时响应、代理感知公平性以及完整兼容性契约，请参阅 CONFIGURATION.md。

来源验证和升级通知： 在 /mcp 上出现的每个 Origin 都会在所有模式下进行验证；对于非浏览器客户端，缺失的 Origin 仍然有效。在非强化模式下，未设置的 MCP_HTTP_ALLOWED_ORIGINS 默认为精确的 HTTP/HTTPS 环回来源 http://127.0.0.1、https://127.0.0.1、http://localhost、https://localhost、http://[::1] 和 https://[::1]，既包括无端口形式，也包括带所配置 MCP_HTTP_PORT 的形式。非空的 MCP_HTTP_ALLOWED_ORIGINS 会替换这些默认值。条目会被去除首尾空白，但除此之外按字面处理；匹配是精确的、区分大小写的字面匹配，包括协议和端口。格式错误、缺少协议、带路径、带尾斜杠或大小写不同的值会静默地不匹配，必须予以纠正。强化模式仍然要求显式允许列表，并增加身份验证和 Host 强制。在解析器、身份验证、速率限制或传输构造之前，/mcp 上无效的现有 Origin 会收到固定的、不反射的 403。/health 位于 MCP 403 边界之外，但使用收窄后的全局 CORS 允许列表。升级之前，使用非环回 Origin 的现有非强化浏览器部署必须设置 MCP_HTTP_ALLOWED_ORIGINS，否则将收到固定的 403。

测试它：

curl http://localhost:3000/health

服务器默认绑定到 127.0.0.1；对于远程或容器化部署，请设置 MCP_HTTP_HOST=0.0.0.0。在将其暴露到网络之前，请启用强化模式（MCP_HTTP_HARDEN），并参阅 CONFIGURATION.md 了解 MCP_HTTP_TRUST_PROXY，以便速率限制和日志使用正确的客户端 IP。

配置

SEARXNG_URL 是唯一必需的变量——将其设置为你的 SearXNG 实例 URL（或分号分隔的可互换副本列表）。其他所有内容都是可选的。

当搜索调用省略 response_format 时，使用 SEARXNG_DEFAULT_RESPONSE_FORMAT 选择 text 或 json；每次调用显式指定的值仍然优先。

有关完整的环境变量参考，请参阅 CONFIGURATION.md，包括身份验证、故障转移/扇出、缓存、超时、代理、TLS、HTTP 传输和强化。

故障排除

有关自托管 SearXNG 配置、直接验证和故障排除，请参阅 使用 mcp-searxng 操作自托管 SearXNG。 如果你不控制该实例，请改用单独的 公共 SearXNG 实例指南。

如果 HTTPS 请求在具有证书错误的 TLS 检查企业代理后面失败，请参阅 TLS / 企业 CA。

来自 SearXNG 的 403 禁止访问

你的 SearXNG 实例可能已禁用 JSON 格式。编辑 settings.yml（通常位于 /etc/searxng/settings.yml）：

search:
  formats:
    - html
    - json

重启 SearXNG（docker restart searxng），然后验证：

curl 'http://localhost:8080/search?q=test&format=json'

你应该会收到 JSON 响应。如果没有，请确认文件已正确挂载且 YAML 缩进有效。

另请参阅：SearXNG 设置文档 · 讨论

无法启用 JSON？（HTML 回退）

如果你必须使用不受你控制的公共实例，且该实例拒绝 format=json（上述 403），请设置选择加入标志，而不是编辑服务器：

在启用之前，请查看公共运营者的政策以及 公共实例使用指南。

{
  "SEARXNG_HTML_FALLBACK": "true"
}

获得 403/404 或非 JSON 响应的搜索随后会自动不带 format=json 重试，并从常规 HTML 结果页面解析。

• 成功时： 你会获得正常结果（标题、URL、摘要）。在 JSON 模式下，它们被标记为 sourceFormat: "html"，文本模式会添加一行 "注意：结果从 SearXNG HTML 回退中解析；元数据有限。" 相关度分数和引擎名称无法从 HTML 中获得。

• 失败时： 解析是尽力而为的，并且因实例的主题/版本而异，因此某些结果可能会丢失或稀疏。如果 HTML 页面本身也失败——仍然被阻止、速率受限（429）、身份验证（401）或 5xx——则回退尝试的错误会被呈现，因此搜索永远不会静默返回空结果。回退仅在 403/404/非 JSON 时触发，绝不会在身份验证或网络错误时触发。

在你控制的实例上启用 JSON（上文）仍然是推荐的设置——回退是一种兼容性辅助手段，而不是替代方案。

贡献

请参阅 CONTRIBUTING.md

许可证

MIT——详情请参阅 LICENSE。