SearXNG MCP Bridge Server

这是一个作为桥接器连接到SearXNG实例的模型上下文协议（MCP）服务器。它允许兼容客户端通过MCP工具使用配置好的SearXNG实例进行搜索。

快速开始（使用npm）

1. 设置SearXNG实例：

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

2. 安装并运行MCP桥接器

   默认（STDIO，未更改）：

   # 直接使用npx运行（默认 - stdio传输）
   npx -y @nitish-raj/searxng-mcp-bridge
   

   可选：作为HTTP服务器运行（新功能，需选择启用）

    # 使用环境变量（推荐）
     TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge
   
   # 或者运行构建包
   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身份验证承载令牌 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 - 通知的服务器发送事件
• 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暴露了端口8081用于HTTP传输。要运行容器并允许HTTP访问：

# 构建（示例）
docker build -t searxng-mcp-bridge .

# 运行映射端口8081
 docker run -d -p 8081:8081 --env SEARXNG_INSTANCE_URL=http://localhost:8080 --name searxng-mcp-bridge searxng-mcp-bridge

# 在容器内运行HTTP传输：
 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