SearXNG MCP Bridge 服务器

这是一个模型上下文协议 (MCP) 服务器，充当 SearXNG 实例的桥梁。它允许兼容的客户端通过 MCP 工具使用配置好的 SearXNG 实例进行搜索。

要求

• Node.js 25.x

• npm 11.x 或更高版本

快速入门 (使用 npm)

1. 设置 SearXNG 实例：

   # Using Docker
   docker run -d -p 8888:8080 --name searxng searxng/searxng

2. 安装并运行 MCP 桥接器

   默认 (STDIO，无需更改)：

   # Run directly with npx (default - stdio transport)
   npx -y @nitish-raj/searxng-mcp-bridge

   可选：作为 HTTP 服务器运行 (新功能，需手动启用)

    # Using env variables (recommended)
     TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge
   
   
   
   # Or run the built bundle
   TRANSPORT=http node build/index.js

3. 在 MCP 配置文件中进行配置 (stdio / 旧版客户端) 添加到您的 MCP 配置文件中 (例如 ~/.vscode-server/.../mcp_settings.json)：

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "npx",
         "args": [
          "-y",
          "@nitish-raj/searxng-mcp-bridge"
          ],
          "env": {
            "SEARXNG_INSTANCE_URL": "http://localhost:8080"
          },
         "disabled": false
       }
     }
   }

HTTP 配置：设置 TRANSPORT=http 以通过 HTTP 而非 stdio 运行桥接器。传输模式可以通过环境变量进行配置。

功能

• 搜索工具：使用带有可配置参数的 SearXNG 进行网络搜索

• 健康检查：监控 SearXNG 实例的连接性和性能

• 双重传输：支持 STDIO (默认) 和 HTTP 传输

• 会话管理：HTTP 传输包含基于会话的连接

• CORS 支持：为 Web 客户端集成提供正确的跨域标头

• 速率限制：内置针对过度请求的保护 (HTTP 模式)

配置

• SEARXNG_INSTANCE_URL — 必需。SearXNG 实例的完整 URL (例如 http://localhost:8080)。

• TRANSPORT — 传输协议：stdio (默认) 或 http

• PORT — HTTP 服务器端口。默认：3000 (开发环境请使用 3002)

• HOST — 服务器绑定地址。默认：127.0.0.1 (容器环境请使用 0.0.0.0)

• CORS_ORIGIN — 允许 CORS 的来源列表，以逗号分隔。默认：localhost:3002 (开发环境) 或 * (生产环境)

• MCP_HTTP_BEARER — 用于 HTTP 身份验证的可选持有者令牌 (bearer token) HTTP 传输功能：

• 使用 mcp-session-id 标头的会话管理

• 带有来源白名单验证的安全 CORS

• 速率限制 (每 IP 每分钟 100 次请求)

• 通过 MCP_HTTP_BEARER 进行可选的持有者身份验证

• DNS 重绑定保护

安全说明：

• CORS 在开发环境中使用安全白名单 (仅限 localhost:3002)

• 生产环境针对凭据请求反映特定来源 (符合 CORS 标准)

• 设置 CORS_ORIGIN 以根据您的用例自定义允许的来源

• 设置 TRANSPORT=stdio 以恢复到 stdio 模式

HTTP 传输

HTTP 传输实现了 MCP 可流式 HTTP 规范 (2025-03-26)，包含以下端点：

MCP 端点：

• POST /mcp - 发送 MCP 请求

• GET /mcp - 用于通知的服务器发送事件 (SSE)

• DELETE /mcp - 终止会话

• OPTIONS /mcp - CORS 预检请求

系统端点：

• GET /healthz - 健康检查和状态

测试 HTTP 端点：

curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

这将返回一个包含可用工具列表 (search 和 health_check) 的 JSON-RPC 响应。

Docker

Dockerfile 为 HTTP 传输暴露了端口 8081。要运行容器并允许 HTTP 访问：

# Build (example)
docker build -t searxng-mcp-bridge .

# Run mapping port 8081
 docker run -d -p 8081:8081 --env SEARXNG_INSTANCE_URL=http://localhost:8080 --name searxng-mcp-bridge searxng-mcp-bridge

# To run HTTP transport inside container:
 docker run -d -p 8081:8081 -e TRANSPORT=http -e PORT=8081 -e SEARXNG_INSTANCE_URL=http://localhost:8080 searxng-mcp-bridge

注意：容器化时请设置 HOST=0.0.0.0 或依赖默认暴露的端口映射。

使用方法

STDIO 客户端：直接使用该工具即可，无需更改配置。

HTTP 客户端：连接到 http://localhost:3002/mcp (开发端口) 并发送 MCP JSON-RPC 请求。

开发

• npm install：安装依赖项。

• npm run build：将 TypeScript 编译为 JavaScript。

• npm run watch：监视更改并自动重新构建。

• npm run inspector：运行 MCP 检查器以测试服务器。

• npm run start:http：在 localhost:3002 上以 HTTP 流模式启动服务器。

迁移与兼容性

向后兼容性：

• STDIO 仍然是默认传输方式 - 现有用户无需更改

• 所有工具名称、参数和响应保持不变

• 配置通过环境变量可选启用

迁移到 HTTP：

• 设置 TRANSPORT=http 以启用 HTTP 传输

• 根据需要配置 PORT 和 HOST

• 更新客户端以使用 HTTP 端点代替 stdio

回滚：

• 设置 TRANSPORT=stdio 或省略该变量以返回到 stdio