Blumira

Blumira MCP 服务

这是一个 Model Context Protocol (MCP) 服务，可让 AI 助手以结构化方式访问 Blumira SIEM 平台的数据和操作。

注意： 此项目由 Wyre Technology 维护。

快速开始

Claude Desktop——下载、打开即可：

1. 从最新版本下载 blumira-mcp.mcpb
2. 打开文件（双击，或将文件拖入 Claude Desktop）
3. 根据提示输入 Blumira JWT 令牌

无需使用终端、编辑 JSON 或安装 Node.js。

Claude Code（CLI）：

claude mcp add blumira-mcp \
  -e BLUMIRA_JWT_TOKEN=your-jwt-token \
  -- npx -y github:WYRE-AI/blumira-mcp

请参阅安装，了解 Docker 和从源代码安装的方法。

功能

• 🔌 MCP 协议兼容性：全面支持 MCP 资源和工具
• 🛡️ 全面的 SIEM 覆盖范围：提供涵盖发现项、Agent/设备、用户、解决方案和 MSP 账户管理的工具
• 🔍 决策树导航：从 blumira_navigate 开始探索各个领域，然后动态加载特定领域的工具
• 🏢 MSP 多租户支持：全面覆盖 MSP 端点，可跨账户管理发现项、Agent 和用户
• 🔒 安全认证：支持 JWT 令牌或 API 密钥（pax8ApiTokenV1）认证
• 🌐 双传输模式：支持 stdio（本地）和 HTTP Streamable（远程/Docker）传输
• 📦 MCPB 打包：通过 MCP Bundle 为桌面客户端提供一键安装
• 🐳 支持 Docker：容器化部署，提供 HTTP 传输和运行状况检查
• ⚡ 速率限制：内置速率限制器，遵循 Blumira API 限制
• 🔎 丰富的筛选功能：支持 .eq、.in、.gt、.lt、.contains、.regex 和否定运算符

安装

选项 1：MCPB Bundle（Claude Desktop）

最简单的方法——无需使用终端、编辑 JSON 或安装 Node.js。

1. 从最新版本下载 blumira-mcp.mcpb
2. 打开文件（双击，或将文件拖入 Claude Desktop）
3. 根据提示输入 Blumira JWT 令牌

对于 Claude Code（CLI），只需一条命令：

claude mcp add blumira-mcp \
  -e BLUMIRA_JWT_TOKEN=your-jwt-token \
  -- npx -y github:WYRE-AI/blumira-mcp

选项 2：Docker

docker compose up

设置 CONDUIT_S2S_SECRET 后，Compose 才会启动。请参阅 Docker 部署。

或者拉取预构建镜像：

# Generate the secret first: openssl rand -hex 32
docker run -d \
  -e CONDUIT_S2S_SECRET \
  -e BLUMIRA_JWT_TOKEN \
  -e AUTH_MODE=env \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/blumira-mcp:latest

镜像默认使用 AUTH_MODE=gateway，并在容器内绑定到 0.0.0.0。如果 CONDUIT_S2S_SECRET 不是有效的密钥，HTTP 服务将拒绝启动（空值和已知占位符，例如 replace-with-a-real-secret，都会导致进程以非零状态退出）。请将端口发布到 127.0.0.1（如上所示）。在网关模式下，每个 /mcp 请求都必须携带供应商凭据（X-Blumira-Client-ID + X-Blumira-Client-Secret，或 X-Blumira-JWT-Token）；服务不会回退到环境凭据。只有在单租户容器需要使用 BLUMIRA_JWT_TOKEN 时，才设置 AUTH_MODE=env。

每个 /mcp 请求还必须携带 X-Gateway-S2S。校验逻辑位于 src/s2s-verify.ts 的 verifyS2sHeader 中：标头值为 t=<unix seconds>,v1=<hex>，其中 hex 是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds> 进行 HMAC-SHA256 计算后的结果（64 位小写十六进制字符）。时间戳与服务器时钟的偏差不得超过 300 秒。缺少标头或标头无效时，将在读取供应商凭据前返回 HTTP 401。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

使用 AUTH_MODE=env 时，签名请求会使用容器中的 BLUMIRA_JWT_TOKEN。使用 AUTH_MODE=gateway 时，还需添加 X-Blumira-JWT-Token，或同时添加 X-Blumira-Client-ID 和 X-Blumira-Client-Secret。

对于无法对请求签名的独立本地使用场景，可设置 MCP_ALLOW_INSECURE_DEV=1，且不要设置 CONDUIT_S2S_SECRET。服务启动时会记录警告、跳过 S2S 校验，并且只绑定到 127.0.0.1。镜像会设置 MCP_HTTP_HOST=0.0.0.0，因此绕过校验时还必须使用 -e MCP_HTTP_HOST=127.0.0.1。任何其他绑定地址都会导致服务拒绝启动。请勿将该端口发布到本地回环接口之外。

选项 3：从源代码构建

git clone https://github.com/WYRE-AI/blumira-mcp.git
cd blumira-mcp
npm ci
npm run build

配置

变量	描述	默认值
BLUMIRA_JWT_TOKEN	用于身份验证的 JWT 令牌（stdio 和 AUTH_MODE=env）	—
MCP_TRANSPORT	传输模式（stdio 或 http）	stdio
MCP_HTTP_PORT	HTTP 服务端口	8080
MCP_HTTP_HOST	HTTP 服务绑定的接口	127.0.0.1
CONDUIT_S2S_SECRET	HTTP 必填。在 /mcp 上针对 X-Gateway-S2S 校验的 HMAC 密钥。使用 openssl rand -hex 32 生成。如果为空或为已知占位符，HTTP 服务会记录错误并以非零状态退出。该值绝不会被记录。	—
MCP_ALLOW_INSECURE_DEV	设置为 1，即可在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。服务会记录警告、不强制执行 S2S 校验，并且只绑定到 127.0.0.1。如果 MCP_HTTP_HOST 不是本地回环地址，服务将拒绝启动。仅限本地开发使用。	未设置
AUTH_MODE	env 使用进程环境凭据（stdio 和单租户 HTTP）。gateway 要求每个请求都携带供应商标头，且绝不会回退到环境凭据。Docker 镜像和 Compose 文件默认使用 gateway。	未设置时为 env；在 Docker 和 Compose 中为 gateway
LOG_LEVEL	日志级别（debug、info、warn、error）	info

/health 和 /healthz 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

域

服务使用决策树导航。使用 blumira_navigate 开始选择域：

域	工具
findings	列出发现项、获取发现项、获取发现项详情、解决发现项、分配负责人、列出/添加评论
agents	列出设备、获取设备、列出 Agent 密钥、获取 Agent 密钥
users	列出用户
resolutions	列出可用的解决方案
msp	列出/获取账户、列出/获取/解决发现项、分配负责人、评论、列出设备/密钥、列出用户

筛选

Blumira 支持在列表端点使用丰富的查询筛选：

status.eq=10              # Exact match
severity.in=HIGH,CRITICAL # Multiple values
created_at.gt=2026-01-01  # Greater than
name.contains=malware     # Substring match
!status.eq=30             # Negation

将筛选条件作为工具输入参数传入，服务会处理查询字符串的构造。

Docker 部署

将 .env.example 复制为 .env 并填写凭据，包括 CONDUIT_S2S_SECRET。如果缺少此变量，Compose 将无法启动，并且只会在 127.0.0.1 上发布 HTTP 端口。

cp .env.example .env
# Edit .env with your Blumira JWT token and CONDUIT_S2S_SECRET
docker compose up -d

开发

npm ci
npm run build       # Build the project
npm run dev         # Watch mode
npm run test        # Run tests
npm run lint        # Type-check
npm run clean       # Remove dist/

贡献

请参阅 CONTRIBUTING.md 了解指南。

许可证

Apache 2.0 — 版权所有 WYRE Technology