KnowBe4

KnowBe4 MCP 服务

用于 KnowBe4 安全意识培训的模型上下文协议（MCP）服务。支持 AI 助手管理钓鱼模拟、培训活动、用户风险评分和安全意识报告。

这是一个 模型上下文协议（MCP） 服务，可将 Claude（或任何兼容 MCP 的 AI）连接到你的 KnowBe4 环境。

属于 MSP Claude Plugins 生态系统——这是一个不断扩展的 MSP 技术栈 AI 集成套件。由 MSP 构建，服务于 MSP。

安装

npm install @wyre-ai/knowbe4-mcp

配置

复制 .env.example。Stdio 和 AUTH_MODE=env 会读取 KnowBe4 变量。网关模式不会读取。

变量	必填	描述
KNOWBE4_API_KEY	用于 stdio 和 AUTH_MODE=env	KnowBe4 API 密钥
KNOWBE4_REGION	否	API 区域：us（默认）、eu、ca、uk 或 de
KNOWBE4_BASE_URL	否	自定义基础 URL（覆盖区域设置）
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	env（镜像外的默认值）或 gateway。容器镜像和 Compose 的默认值为 gateway。网关模式要求每个 /mcp 请求都携带 X-KnowBe4-API-Key（X-KnowBe4-Region 可选），且绝不会回退到 KNOWBE4_*。
CONDUIT_S2S_SECRET	HTTP 必填	服务间密钥。如果此项为空或为已知占位符，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 不是环回地址，则会拒绝启动。已知占位符密钥仍会被拒绝。
MCP_HTTP_HOST	否	设置了真实 CONDUIT_S2S_SECRET 时的绑定地址。未设置时使用 0.0.0.0，这是容器镜像设置的值，因此容器部署会在容器内的所有网络接口上监听。没有密钥时，开发绕过模式会改为绑定 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

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

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。其值为 t=<unix seconds>,v1=<hex>，其中 v1 是以 CONDUIT_S2S_SECRET 为密钥、对精确字符串 t=<unix seconds> 计算的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的偏差不得超过 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-KnowBe4-API-Key（X-KnowBe4-Region 可选）。该标头是此请求唯一的凭据来源。缺少该标头的请求会返回 401，且不会从环境变量读取 KNOWBE4_API_KEY。

使用方法

使用 Claude Desktop 运行

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "knowbe4-mcp": {
      "command": "npx",
      "args": ["@wyre-ai/knowbe4-mcp"],
      "env": {
        "KNOWBE4_API_KEY": "your-knowbe4-api-key"
      }
    }
  }
}

使用 Claude Code（CLI）运行

claude mcp add knowbe4-mcp \
  -e KNOWBE4_API_KEY=your-value \
  -- npx -y @wyre-ai/knowbe4-mcp

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。请将端口发布到回环地址，并传入真实的 S2S 密钥。在网关模式下，KnowBe4 API 密钥会随每个请求通过 X-KnowBe4-API-Key 传入；不会从环境变量中读取。

docker build -t knowbe4-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  knowbe4-mcp

当 CONDUIT_S2S_SECRET 未设置时，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，不会设置 KNOWBE4_API_KEY 或 env_file，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 KNOWBE4_API_KEY：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e KNOWBE4_API_KEY=your-value \
  -e KNOWBE4_REGION=us \
  -p 127.0.0.1:8080:8080 \
  knowbe4-mcp

不使用密钥的本地 HTTP 仅限开发环境。它会绑定到 127.0.0.1 并记录警告。将 MCP_HTTP_HOST 设为非回环地址会导致启动退出：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

可用域

账户

账户信息和设置

群组

用户群组管理

钓鱼

钓鱼模拟活动

报告

安全意识报告

培训

培训活动管理

用户

用户管理和风险评分

交互式用户卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，knowbe4_users_get 会呈现为交互式卡片，显示用户的风险评分、易受钓鱼攻击百分比、风险评分趋势和个人资料详情；在其他宿主中，纯 JSON 行为保持不变。该卡片默认采用中性样式且为只读（不支持写入往返），并可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌化，无需重新构建。

开发

# Clone the repository
git clone https://github.com/WYRE-AI/knowbe4-mcp.git
cd knowbe4-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

贡献

欢迎贡献！如有 CONTRIBUTING.md，请参阅该文件；也可以创建议题来讨论变更。

许可证

本项目采用 Apache License, Version 2.0。详情请参阅 LICENSE。