Huntress

Huntress MCP 服务

一个 Model Context Protocol (MCP) 服务，可为 AI 助手提供对 Huntress 网络安全平台数据和操作的结构化访问。

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

快速开始

Claude Desktop — 下载、打开，即可使用：

1. 从最新版本下载 huntress-mcp.mcpb
2. 打开文件（双击或拖入 Claude Desktop）
3. 根据提示输入 Huntress 凭据（API Key、API Secret）

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

Claude Code（命令行）：

claude mcp add huntress-mcp \
  -e HUNTRESS_API_KEY=your-api-key \
  -e HUNTRESS_API_SECRET=your-api-secret \
  -- npx -y github:WYRE-AI/huntress-mcp

Docker 和从源代码安装方法请参阅安装。

功能

• 🔌 MCP 协议兼容性：全面支持 MCP 资源和工具
• 🛡️ 全面覆盖安全领域：涵盖 Agent、组织、事件、升级、账单、信号和用户的工具
• 🔍 决策树导航：从 huntress_navigate 开始探索各领域，然后动态加载领域专属工具
• 📝 CRUD 操作：支持创建、读取、更新和删除组织、成员关系、事件等
• 🔒 安全认证：使用 Huntress API 凭据进行 HTTP Basic Auth
• 🌐 双传输方式：同时支持 stdio（本地）和 HTTP Streamable（远程／Docker）传输
• 📦 MCPB 打包：通过 MCP Bundle 为桌面客户端提供一键安装
• 🐳 支持 Docker：容器化部署，提供 HTTP 传输和运行状况检查
• ⚡ 速率限制：内置速率限制器，遵循 Huntress API 限制（60 req/min）
• 📊 结构化日志记录：全面记录日志，级别可配置

目录

• 安装
• 配置
• 使用方法
• 领域
• Docker 部署
• 开发
• 测试
• 贡献
• 许可证

安装

选项 1：MCPB Bundle（Claude Desktop）

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

1. 从最新版本下载 huntress-mcp.mcpb
2. 打开文件（双击或拖入 Claude Desktop）
3. 根据提示输入 Huntress 凭据（API Key、API Secret）

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

claude mcp add huntress-mcp \
  -e HUNTRESS_API_KEY=your-api-key \
  -e HUNTRESS_API_SECRET=your-api-secret \
  -- npx -y github:WYRE-AI/huntress-mcp

选项 2：Docker

此镜像会在容器内监听 0.0.0.0，并默认使用 AUTH_MODE=gateway。将端口发布到 loopback，并传入服务间密钥。在网关模式下，Huntress 凭据会作为请求头随每个请求传入；不会从环境变量中读取。

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/huntress-mcp:latest

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

选项 3：从源代码安装

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

配置

复制 .env.example，并设置以下变量。

变量	必需	说明
HUNTRESS_API_KEY	用于 stdio 和 AUTH_MODE=env	Huntress API 公钥
HUNTRESS_API_SECRET	用于 stdio 和 AUTH_MODE=env	Huntress API 密钥
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 默认值）或 env。Gateway 模式要求每个 /mcp 请求都包含 X-Huntress-Api-Key 和 X-Huntress-Api-Secret，且绝不会回退到 HUNTRESS_*。只有 S2S 身份验证成功后，env 模式才会使用这些变量。
CONDUIT_S2S_SECRET	HTTP 必需	服务间密钥。若该值为空或为已知占位值（changeme、secret、replace-me、your-s2s-secret 及其他示例值），HTTP 服务会记录错误并以非零状态码退出。未设置此值时，Compose 不会启动。切勿提交真实值。使用 openssl rand -hex 32 生成密钥。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时将其精确设置为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告、不强制要求 X-Gateway-S2S，且仅监听 127.0.0.1。非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录覆盖情况。已知占位密钥仍会被拒绝。
MCP_HTTP_HOST	否	设置 CONDUIT_S2S_SECRET 时的绑定地址。未设置时默认为 127.0.0.1。容器镜像将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
LOG_LEVEL	否	日志级别（debug、info、warn、error）。默认为 info。

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

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S：

t=<unix seconds>,v1=<hex hmac-sha256>

v1 是对准确消息 t=<unix seconds> 进行 HMAC-SHA256 运算的结果，使用 CONDUIT_S2S_SECRET 作为密钥，并以十六进制编码。时间戳与服务器时钟的偏差必须在 300 秒以内。缺少或无效的标头会返回 401。密钥绝不会写入日志。

import { createHmac } from 'node:crypto';

const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.CONDUIT_S2S_SECRET).update(`t=${t}`).digest('hex');
const xGatewayS2s = `t=${t},v1=${v1}`;

在 AUTH_MODE=gateway 模式下，/mcp 还要求包含 X-Huntress-Api-Key 和 X-Huntress-Api-Secret。这些标头是该请求唯一的凭据来源。缺少任一标头的请求都会返回 401，且不会回退到 HUNTRESS_API_KEY / HUNTRESS_API_SECRET。

await fetch('http://127.0.0.1:8080/mcp', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    accept: 'application/json, text/event-stream',
    'x-gateway-s2s': xGatewayS2s,
    'x-huntress-api-key': apiKey,
    'x-huntress-api-secret': apiSecret,
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
});

域

该服务使用决策树导航。先使用 huntress_navigate 选择一个域：

域	工具
accounts	获取账户信息、获取当前操作者
agents	列出 Agent、按 ID 获取 Agent
organizations	列出、获取、创建、更新、删除组织
incidents	事件报告（列出/获取/解决）、修复措施（列出/获取/批准/拒绝）、升级事件（列出/获取/解决）
billing	账单报告、摘要报告
signals	列出/获取安全信号
users	成员管理 CRUD（列出/获取/创建/更新/删除）

Docker 部署

完整配置请参见 docker-compose.yml。仓库中提供的 Compose 服务采用 gateway 模式。它不会设置 HUNTRESS_API_KEY 或 HUNTRESS_API_SECRET，也不会使用 env_file，因此项目 .env 无法向容器注入静态的供应商凭据。Compose 仍会从该文件插入 CONDUIT_S2S_SECRET，未设置时不会启动。端口仅发布到 127.0.0.1。

cp .env.example .env
# Set CONDUIT_S2S_SECRET. Leave it empty in the example; never commit a real value.
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up -d

单租户 HTTP（AUTH_MODE=env）仍然要求设置 S2S 密钥，然后使用 HUNTRESS_API_KEY 和 HUNTRESS_API_SECRET。它与 gateway Compose 服务相互独立：

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e HUNTRESS_API_KEY=your-key \
  -e HUNTRESS_API_SECRET=your-secret \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/huntress-mcp:latest

不使用密钥的本地 HTTP 仅用于开发。它只绑定到 127.0.0.1，并会记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

开发

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/

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

测试

npm test            # Run test suite
npm run test:watch  # Watch mode

贡献

请参见 CONTRIBUTING.md 了解指南。

许可证

Apache 2.0 — 版权所有 WYRE Technology