SearXNG MCP

SearXNG MCP 服务

一个模型上下文协议（MCP）服务，通过集成 SearXNG 实例提供网页搜索功能。

功能

• 网页搜索：在多个引擎间执行强大的聚合搜索。
• 发现：以编程方式获取可用的类别和引擎。
• 无状态 HTTP：兼容任何标准 JSON-RPC 客户端。
• 灵活配置：支持环境变量和命令行参数。

使用 compose.yml 运行 SearXNG 和 MCP 服务的示例

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - "${SEARXNG_PORT:-8080}:8080"
    volumes:
      - "${SEARXNG_VOL_CONFIG:-searxng-config}:/etc/searxng/"
      - "${SEARXNG_VOL_DATA:-searxng-data}:/var/cache/searxng/"
    restart: always

  searxng-mcp:
    image: ghcr.io/aicrafted/searxng-mcp:latest
    restart: unless-stopped
    depends_on:
      # Ensure SearXNG starts before the MCP server
      - searxng
    environment:
      SEARXNG_URL: "${SEARXNG_URL:-http://searxng:8080}"
      MCP_HOST: "${MCP_HOST:-127.0.0.1}"
      MCP_PORT: "${MCP_PORT:-32123}"
      MCP_TRANSPORT: "${MCP_TRANSPORT:-http}"
      MCP_ALLOWED_HOSTS: "${MCP_ALLOWED_HOSTS:-localhost:*,127.0.0.1:*}"
      MCP_ALLOWED_ORIGINS: "${MCP_ALLOWED_ORIGINS:-http://localhost:*,http://127.0.0.1:*}"
      MCP_DISABLE_DNS_REBINDING_PROTECTION: "${MCP_DISABLE_DNS_REBINDING_PROTECTION:-false}"
    ports:
      - "${MCP_PORT:-32123}:${MCP_PORT:-32123}"

volumes:
  searxng-config:
  searxng-data:

**重要：**在 SearXNG 的 settings.yml 中启用 JSON 响应，否则 MCP 服务无法读取搜索结果：

search:
  formats:
    - html
    - json

.env 示例

# SearXNG url should be visible by the MCP server inside docker, so use internal service port here
SEARXNG_URL=http://searxng:8080
# Public SearXNG port
SEARXNG_PORT=8080
# Searxng config and data volumes, start with "./" if You want to bind dir instead using volume
SEARXNG_VOL_CONFIG=searxng-config
SEARXNG_VOL_DATA=searxng-data

# MCP server host, port and transport ("stdio", "sse", "http")
MCP_HOST=127.0.0.1
MCP_PORT=32123
MCP_TRANSPORT=http

# MCP DNS rebinding protection (see https://github.com/modelcontextprotocol/python-sdk/issues/1798 for details)
MCP_ALLOWED_HOSTS=localhost:*,127.0.0.1:*
MCP_ALLOWED_ORIGINS=http://localhost:*,http://127.0.0.1:*
# MCP_DISABLE_DNS_REBINDING_PROTECTION=true

MCP 客户端配置

HTTP 传输（推荐）

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://localhost:32123/mcp"
    }
  }
}

SSE 传输

{
  "mcpServers": {
    "searxng": {
      "type": "sse",
      "url": "http://localhost:32123/sse"
    }
  }
}

**注意：**SSE 传输使用 /sse 端点，而不是 /mcp。HTTP 传输使用 /mcp。

从源代码运行的先决条件

• Python 3.10+
• 正在运行的 SearXNG 实例。

安装

1. 克隆仓库并进入该目录。
2. 安装依赖项：

   pip install -r requirements.txt
   

3. 设置 .env 文件（可选）。

配置

服务从命令行参数和环境变量读取配置。命令行参数会覆盖启动时使用的对应默认值。

变量	默认值	说明
SEARXNG_URL	http://localhost:8080	SearXNG 实例的 URL。
SEARXNG_PORT	8080	compose 示例中 SearXNG 容器映射到主机的公开端口。
SEARXNG_VOL_CONFIG	searxng-config	compose 示例中挂载到 /etc/searxng/ 的 Docker 卷或主机路径。
SEARXNG_VOL_DATA	searxng-data	compose 示例中挂载到 /var/cache/searxng/ 的 Docker 卷或主机路径。
MCP_HOST	127.0.0.1	HTTP/SSE 传输绑定的主机。在 Docker 中发布端口时使用 0.0.0.0。
MCP_PORT	8000	HTTP/SSE 传输绑定的端口。
MCP_TRANSPORT	stdio	传输模式：stdio、http 或 sse。
MCP_ALLOWED_HOSTS	SDK 对 localhost 的默认值	以逗号分隔的允许使用的 Host 标头，用于防范 DNS 重绑定。
MCP_ALLOWED_ORIGINS	SDK 对 localhost 的默认值	以逗号分隔的允许使用的 Origin 标头，用于防范 DNS 重绑定。
MCP_DISABLE_DNS_REBINDING_PROTECTION	false	设为 true 可关闭 SDK 的 DNS 重绑定防护。

使用方法

使用 uv 或标准 Python 运行服务：

python searxng_mcp.py --transport http --port 32123 --searxng http://searx.lan

使用 Docker 运行

1. 构建镜像：

   docker build -t searxng-mcp .
   

2. 运行容器：

   docker run -d \
     -p 32123:32123 \
     --env-file .env \
     --name searxng-mcp \
     searxng-mcp
   

传输选项

• stdio：标准输入/输出（某些 MCP 客户端的默认选项）。
• http：无状态 HTTP（streamable-http）。
• sse：服务器发送事件。

DNS 重绑定防护

较新版本的 MCP Python SDK 会验证 HTTP/SSE 传输的 Host 和 Origin 标头，以保护本地服务免受 DNS 重绑定攻击。如果通过 Docker、反向代理或自定义域名公开服务时收到 421 Invalid Host Header，请明确配置允许列表：

MCP_ALLOWED_HOSTS=localhost:*,127.0.0.1:*,mcp.example.com:*
MCP_ALLOWED_ORIGINS=http://localhost:*,http://127.0.0.1:*,https://mcp.example.com

对于可信的本地开发环境，或由其他基础设施层处理此验证的情况，可以关闭 SDK 防护：

MCP_DISABLE_DNS_REBINDING_PROTECTION=true

请谨慎关闭防护；推荐设置 MCP_ALLOWED_HOSTS 和 MCP_ALLOWED_ORIGINS。

---

搜索能力指南

SearXNG 会聚合来自各种来源的结果。本指南概述了通过 web_search 工具提供的功能。

搜索类别

类别可按内容类型细化搜索。请在 categories 参数中使用这些类别（以逗号分隔）。

类别	描述
general	默认网页搜索（Google、Brave、DuckDuckGo 等）
images	图片搜索结果
videos	来自 YouTube、Vimeo 等平台的视频内容
news	最新新闻文章
map	地理和地图信息
it	IT 相关搜索（StackOverflow、GitHub 等）
science	科学论文和文章（ArXiv、Google Scholar）
files	种子和文件搜索
social_media	社交平台上的帖子和个人资料

支持的引擎

SearXNG 可查询 130 多个引擎。配置的引擎通常包括：

• 网页：Google、Brave、DuckDuckGo、Qwant、Startpage
• 知识：Wikipedia、Wikidata
• 开发：GitHub、StackOverflow、PyPI
• 社交：Reddit、Twitter/X

高级搜索参数

• categories：按特定类型筛选（例如 news,it）。
• engines：指定搜索引擎（例如 google,wikipedia）。
• language：指定搜索语言（例如 en、es、fr）。
• pageno：浏览多个结果页。
• time_range：按日期筛选（day、month、year）。
• safesearch：控制内容过滤（0=无，1=中等，2=严格）。

程序化发现

使用 web_search_info 工具，从你的实例动态获取已启用类别和引擎的列表。

Windows 故障排查

Docker 容器运行时无法访问 localhost

症状： http://localhost:<port>/ 返回连接被拒绝或访问了错误的服务， 但在容器内使用 curl 一切正常。

根本原因：WSL2 端口转发残留

WSL2 会使用 wslrelay.exe 自动将端口从 Linux 虚拟机转发到 Windows 主机。 当 WSL 中的进程监听某个端口时，WSL 会在 Windows 端创建一个绑定到 [::1]:<port> （IPv6 环回地址）的转发项。

当 WSL 进程停止时，wslrelay.exe 通常不会释放该端口。转发项会作为僵尸监听器， 继续留在 [::1]:<port> 上。

之后，当 Docker 将容器映射到同一个主机端口时，它会正确绑定到 0.0.0.0:<port>，但 [::1]:<port> 已被陈旧的转发项占用。

在 Windows 上，localhost 会优先解析为 ::1（IPv6）。因此，浏览器和 curl 请求 localhost:<port> 时会命中失效的 wslrelay.exe 项，而不是 Docker 容器， 从而导致连接错误或收到意外响应。

通过显式 IPv4 地址 127.0.0.1:<port> 连接可以绕过该转发项，正确访问 Docker。

如何诊断：

# Check what is listening on the port
netstat -ano | findstr :<port>

# Identify the processes
Get-Process -Id <pid1>,<pid2> | Select-Object Id,Name

如果你看到同一端口对应两个条目——一个由 com.docker.backend 占用，另一个由 wslrelay 占用——这就是问题所在。

解决方法：

选项	命令	备注
直接使用 IPv4	http://127.0.0.1:<port>/	立即生效，无需重启
重启 WSL	wsl --shutdown	清除所有陈旧的转发项；下次使用时 WSL 会重新启动
重新映射 Docker 端口	在 docker run -p 或 docker-compose.yml 中更改主机端口	完全避免端口冲突

永久修复：

执行 wsl --shutdown 后，重启 Docker 容器。届时转发项将不复存在， localhost:<port> 会正常工作，直到 WSL 再次使用同一端口。

预防措施：

如果你经常在 WSL 和 Docker 中运行使用同一端口的服务，建议选择以下做法之一：

• 始终使用 Docker 运行该服务，不要直接在 WSL 中运行
• 为 WSL 开发实例和 Docker 生产实例使用不同的端口
• 在 docker-compose.yml 中添加显式绑定 127.0.0.1:<port>:<port>，以强制使用 IPv4

---

相关内容

• WSL2 网络文档
• WSL GitHub 问题跟踪器：搜索 wslrelay port leak