SearXNG MCP 服务器

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

功能特性

• 网页搜索：跨多个搜索引擎执行强大的聚合搜索。

• 发现：以编程方式检索可用的类别和搜索引擎。

• 无状态 HTTP：兼容任何标准的 JSON-RPC 客户端。

• 灵活配置：支持环境变量和命令行参数。

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

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - 8080:8080
    volumes:
      - ./searxng/etc/:/etc/searxng/
      - ./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: http://searxng:8080
      MCP_HOST: 0.0.0.0
      MCP_PORT: 32123
      MCP_TRANSPORT: "http"
    ports:
      - "32123:32123"

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://your-searxng-instance:8080
   MCP_PORT=32123
   MCP_HOST=127.0.0.1

使用方法

使用 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 \
     -e SEARXNG_URL=http://your-searxng-instance:8080 \
     --name searxng-mcp \
     searxng-mcp

传输选项

• stdio：标准输入/输出（某些 MCP 客户端的默认设置）。

• http：无状态 HTTP (streamable-http)。

• sse：服务器发送事件 (Server-Sent Events)。

搜索能力指南

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

搜索类别

类别有助于按内容类型优化搜索。在 categories 参数中使用这些类别（以逗号分隔）。

支持的搜索引擎

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 VM 转发到 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 拥有——这就是问题所在。

解决方法：

永久修复：

执行 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