AI导哈

SearXNG MCP桥接服务器

一个将SearXNG元搜索引擎与MCP协议桥接的服务器，允许MCP兼容客户端通过自托管、尊重隐私的搜索引擎执行网络搜索。

  • by nitish-raj
  • JavaScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 nitish-raj/searxng-mcp-bridge

使用说明

SearXNG MCP网桥服务器

一 MCP（模型上下文协议） 桥接到某个服务器的服务器 SearXNG 元搜索引擎实例。它将SearXNG搜索功能作为MCP工具公开，允许任何兼容MCP的客户端（Claude Desktop、Cursor、opencode等）通过自托管、尊重隐私的搜索引擎执行网络搜索。

需求

  • Node.js>=25.0.0<26
  • 跑步 SearXNG 启用JSON API的实例

快速开始

1.设置SearXNG实例

docker run -d -p 8080:8080 --name searxng searxng/searxng

2.运行MCP桥

STDIO模式 （默认情况下，适用于Claude Desktop等MCP客户端）：

npx -y @nitish-raj/searxng-mcp-bridge

HTTP模式 （适用于网络/远程客户端）：

TRANSPORT=http PORT=3002 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge

通过CLI标志 （替代env-var）：

SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge --transport=http

3.配置您的MCP客户端

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上， %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

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

光标/VS代码 (mcp_settings.json):

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

MCP工具

search

使用配置的SearXNG实例执行web搜索。

参数：

参数 类型 必填 说明
query string 是 搜索查询字符串
language string 否 结果的语言代码（例如。， en-US, fr, de)
categories string[] 否 要搜索的类别（例如。， ["general", "images", "news"])
time_range string 否 时间范围筛选器： day, week, month, year
safesearch number 否 安全搜索级别： 0 关 1 （中等）， 2 （严格）
format string 否 结果格式： json （默认）或 html
max_results number 否 返回的最大结果数

示例响应：

{
  "query": "test query",
  "number_of_results": 10,
  "results": [
    {
      "url": "https://example.com",
      "title": "Example Title",
      "content": "Snippet of the search result...",
      "engine": "google",
      "score": 1.0
    }
  ]
}

health_check

检查SearXNG实例和网桥服务器的运行状况和连接状态。

参数： 无

示例响应：

{
  "status": "healthy",
  "searxng_instance": "http://localhost:8080",
  "searxng_status": "healthy",
  "response_time_ms": 42,
  "cache_size": 3,
  "debug_mode": false,
  "version": "0.11.19",
  "timestamp": "2026-05-16T12:00:00.000Z"
}

特性

  • 搜索工具 --使用可配置的语言、类别、时间范围、安全搜索和结果限制执行网络搜索
  • 健康检查 --监控SearXNG连接、响应时间、缓存大小和版本
  • 双重运输 --支持STDIO（默认）和HTTP流传输
  • 响应缓存 --5分钟TTL缓存，定期清理以减少重复请求
  • 重试逻辑 --针对暂时性故障，采用指数回退（3次尝试）自动重试
  • 启动验证 --在启动时通过详细的错误诊断验证SearXNG连接
  • 会话管理 --HTTP传输包括基于UUID的会话跟踪，通过 mcp-session-id 标头
  • CORS支持 --可配置的源白名单，具有适当的飞行前处理
  • 速率限制 --HTTP模式下的内置保护（每个IP每分钟100个请求）
  • 承载身份验证 --HTTP端点的可选基于令牌的身份验证
  • 调试日志记录 --删除敏感信息（令牌、会话ID、URL）的编辑日志
  • DNS重新绑定保护 --防止HTTP模式下的基于DNS的攻击
  • 优雅关闭 --正确清理SIGINT/SIGTERM上的传输和HTTP服务器

配置

环境变量

变量 必填 默认 描述
SEARXNG_INSTANCE_URL 是 -- SearXNG实例的完整URL（例如。， http://localhost:8080)
TRANSPORT 没有 stdio 传输协议： stdio 或 http
PORT 没有 3002 HTTP服务器端口（当 TRANSPORT=http)
HOST 没有 127.0.0.1 服务器绑定地址（使用 0.0.0.0 集装箱）
CORS_ORIGIN 没有 localhost:3002 （dev）/ * （prod） CORS允许使用逗号分隔的起源
MCP_HTTP_BEARER 没有 -- HTTP端点身份验证的承载令牌
SEARXNG_BRIDGE_DEBUG 没有 false 启用调试日志记录(true 启用）

CLI标志

标志 描述
--transport <stdio|http> 运输模式（覆盖 TRANSPORT ） 。

HTTP传输

HTTP传输实现了 MCP流式HTTP规范 (2025-03-26).

终点：

方法 路径 描述
POST /mcp 发送MCP JSON-RPC请求；初始化新会话
GET /mcp 服务器发送通知的事件流
DELETE /mcp 终止会话
OPTIONS /mcp CORS飞行前请求
GET /healthz 健康检查（退货 { "status": "ok", "version": "..." })

通过HTTP进行初始化和搜索：

# 1. Initialize a session
curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# 2. List tools (use mcp-session-id from step 1 response)
curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 3. Perform a search
curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search","arguments":{"query":"hello world"}}}'

码头工人

Dockerfile基于 node:25-alpine 并暴露端口 8081.

# Build
docker build -t searxng-mcp-bridge .

# Run in STDIO mode (default)
docker run -d \
  -e SEARXNG_INSTANCE_URL=http://host.docker.internal:8080 \
  searxng-mcp-bridge

# Run in HTTP mode
docker run -d -p 8081:8081 \
  -e TRANSPORT=http \
  -e PORT=8081 \
  -e HOST=0.0.0.0 \
  -e SEARXNG_INSTANCE_URL=http://host.docker.internal:8080 \
  searxng-mcp-bridge

注： 使用 HOST=0.0.0.0 当在容器内运行时，允许外部连接。

发展

npm install          # Install dependencies
npm run dev          # Run with tsx (TypeScript execution, no build step)
npm run build        # Compile TypeScript to JavaScript
npm run watch        # Watch for changes and rebuild automatically
npm run start        # Run the compiled server (stdio mode)
npm run start:http   # Run the compiled server (HTTP mode on port 3002)
npm run inspector    # Run MCP inspector for interactive testing

发布脚本：

npm run release:patch   # Bump patch version (0.11.x)
npm run release:minor   # Bump minor version (0.x.0)
npm run release:major   # Bump major version (x.0.0)

通过以下方式自动发布 请释放 Renovate用于依赖性管理。

贡献

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feat/your-feature
  3. 按照现有代码样式进行更改
  4. 确保 npm run build 通过
  5. 使用打开pull请求 PR模板

欢迎通过以下方式提交Bug报告和功能请求 GitHub问题.

许可证

麻省理工学院 --版权所有（c）2025 Nitish Raj

相关 MCP