SearXNG MCP Bridge

SearXNG MCP网桥服务器


这是一个模型上下文协议（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

1. 安装并运行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

1. 在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":{}}'

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

码头工人

Dockerfile公开端口 8081 用于HTTP传输。要运行容器并允许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