knowbe4-mcp
KnowBe4 MCP Server
A Model Context Protocol (MCP) server for KnowBe4 security awareness training. Enables AI assistants to manage phishing simulations, training campaigns, user risk scoring, and security awareness reporting.
This is a Model Context Protocol (MCP) server that connects Claude (or any MCP-compatible AI) to your KnowBe4 environment.
Part of the MSP Claude Plugins ecosystem — a growing suite of AI integrations for the MSP stack. Built by MSPs, for MSPs.
Installation
npm install @wyre-ai/knowbe4-mcpRelated MCP server: ninjaone-mcp
Configuration
Copy .env.example. Stdio and AUTH_MODE=env read the KnowBe4 variables. Gateway mode does not.
Variable | Required | Description |
| For stdio and | KnowBe4 API key |
| No | API region: |
| No | Custom base URL (overrides region) |
| No |
|
| No |
|
| Yes for HTTP | Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder. Compose will not start without it. Never commit a real value. Generate one with |
| No | Set to |
| No | Bind address when a real |
| No | HTTP port. Defaults to |
/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The value is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of the exact string t=<unix seconds> keyed by CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401. The secret is never written to logs.
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}`;In AUTH_MODE=gateway, /mcp also requires X-KnowBe4-API-Key (X-KnowBe4-Region is optional). That header is the only credential source for the request. A request missing it returns 401 and does not read KNOWBE4_API_KEY from the environment.
Usage
Running with Claude Desktop
Add to your Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"knowbe4-mcp": {
"command": "npx",
"args": ["@wyre-ai/knowbe4-mcp"],
"env": {
"KNOWBE4_API_KEY": "your-knowbe4-api-key"
}
}
}
}Running with Claude Code (CLI)
claude mcp add knowbe4-mcp \
-e KNOWBE4_API_KEY=your-value \
-- npx -y @wyre-ai/knowbe4-mcpDocker
The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real S2S secret. In gateway mode, the KnowBe4 API key arrives on each request as X-KnowBe4-API-Key; it is not read from the environment.
docker build -t knowbe4-mcp .
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-p 127.0.0.1:8080:8080 \
knowbe4-mcpCompose refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, does not set KNOWBE4_API_KEY or env_file, and publishes 127.0.0.1:8080:8080:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses 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-mcpLocal HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST makes startup exit:
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm startAvailable Domains
Account
Account information and settings
Groups
User group management
Phishing
Phishing simulation campaigns
Reporting
Security awareness reports
Training
Training campaign management
Users
User management and risk scoring
Interactive User Card (MCP Apps)
knowbe4_users_get renders as an interactive card in MCP Apps hosts
(Claude Desktop/web) showing the user's risk score, phish-prone percentage,
risk-score trend, and profile details; plain-JSON behavior is unchanged in
other hosts, and the card is read-only (no write round-trip). The card is
neutral by default and brandable via window.__BRAND__ injection or
MCP_BRAND_* env vars (MCP_BRAND_NAME, MCP_BRAND_LOGO_URL,
MCP_BRAND_PRIMARY_COLOR, MCP_BRAND_ACCENT_COLOR, MCP_BRAND_BG,
MCP_BRAND_TEXT) — no rebuild needed.
Development
# 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 testContributing
Contributions are welcome! Please see CONTRIBUTING.md if present, or open an issue to discuss changes.
License
Licensed under the Apache License, Version 2.0. See LICENSE for details.
Available Tools
30 toolsknowbe4_account_getA
Get KnowBe4 account information including subscription level, number of seats, admin details, and current risk score.
Inputs: no named parameters.
knowbe4_account_risk_score_historyB
Get the account-level risk score history over time. Useful for tracking overall security posture improvement.
Inputs: page, per_page.
knowbe4_backC
No-op tool for backwards compatibility. All tools are always available.
Inputs: no named parameters.
knowbe4_groups_getB
Get detailed information about a specific KnowBe4 group by ID, including risk score and member count.
Inputs: group_id (required).
knowbe4_groups_listA
List all KnowBe4 groups. Returns group names, member counts, and current risk scores.
Inputs: page, per_page.
knowbe4_groups_membersB
Get all members of a specific group. Returns user details for each member.
Inputs: group_id (required), page, per_page.
knowbe4_groups_risk_score_historyB
Get a group's risk score history over time. Useful for comparing security posture across departments or teams.
Inputs: group_id (required), page, per_page.
knowbe4_phishing_campaigns_getB
Get detailed information about a specific phishing campaign by ID, including all associated security tests.
Inputs: campaign_id (required).
knowbe4_phishing_campaigns_listB
List all phishing simulation campaigns. Returns campaign names, status, creation dates, and associated security test counts.
Inputs: page, per_page.
knowbe4_phishing_campaign_testsC
List all Phishing Security Tests (PSTs) for a specific campaign.
Inputs: campaign_id (required), page, per_page.
knowbe4_phishing_security_test_getA
Get detailed results for a specific Phishing Security Test (PST) by ID. Includes phish-prone percentage, clicked/opened/reported counts.
Inputs: pst_id (required).
knowbe4_phishing_security_test_recipientB
Get a specific recipient's detailed result for a PST, including click time, open time, and reported status.
Inputs: pst_id (required), recipient_id (required).
knowbe4_phishing_security_test_recipientsB
Get recipient-level results for a specific PST. Shows which users clicked, opened, reported, or were otherwise affected.
Inputs: pst_id (required), page, per_page.
knowbe4_phishing_security_tests_listA
List all Phishing Security Tests (PSTs) across all campaigns. Returns test status, phish-prone percentage, and recipient counts.
Inputs: page, per_page.
knowbe4_policies_getC
Get detailed information about a specific policy by ID, including acknowledgment status.
Inputs: policy_id (required).
knowbe4_policies_listC
List all security policies. Returns policy names, status, and acknowledgment requirements.
Inputs: page, per_page.
knowbe4_reporting_phishing_summaryA
Get a summary of all phishing security tests including overall phish-prone percentage, total tests run, and aggregate click/open/report rates. Fetches all PSTs and computes statistics.
Inputs: page, per_page.
knowbe4_reporting_risk_overviewA
Get an overview of account risk posture including current risk score, recent risk score trend, and highest-risk groups.
Inputs: no named parameters.
knowbe4_reporting_training_summaryB
Get a summary of all training campaigns including total enrollments, completion counts, and overall completion rate.
Inputs: page, per_page.
knowbe4_statusC
Show credentials status and available domains. Also verifies API credentials are configured.
Inputs: no named parameters.
knowbe4_store_purchases_getB
Get detailed information about a specific store purchase by ID.
Inputs: purchase_id (required).
knowbe4_store_purchases_listC
List all store purchases (training content bought from the KnowBe4 ModStore). Shows purchased modules and content.
Inputs: page, per_page.
knowbe4_training_campaigns_getA
Get detailed information about a specific training campaign by ID, including modules, enrollments, and completion statistics.
Inputs: campaign_id (required).
knowbe4_training_campaigns_listC
List all training campaigns. Returns campaign names, status, enrollment counts, and completion rates.
Inputs: page, per_page.
knowbe4_training_enrollments_getB
Get detailed information about a specific training enrollment by ID, including module progress and completion date.
Inputs: enrollment_id (required).
knowbe4_training_enrollments_listB
List all training enrollments. Shows which users are enrolled in which training modules and their completion status.
Inputs: page, per_page.
knowbe4_users_getA
Get detailed information about a specific KnowBe4 user by ID, including their risk score, phish-prone percentage, training status, and group memberships.
Inputs: user_id (required).
knowbe4_users_listA
List KnowBe4 users with optional filtering by status or group. Returns paginated results including email, name, risk score, and department.
Inputs: page, status, group_id, per_page.
knowbe4_users_risk_score_historyB
Get a specific user's risk score history over time. Useful for tracking individual improvement in security awareness.
Inputs: user_id (required), page, per_page.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Each tool targets a distinct resource (campaigns, security tests, recipients, training, groups, users, reporting) with clear specificity. Tools like phishing_security_tests_list vs phishing_campaign_tests are differentiated by scope (all tests vs per-campaign), and the naming plus descriptions make boundaries clear.
All tools follow a consistent knowbe4_<domain>_<resource>_<action> pattern. The hierarchy is predictable: domain prefixes (phishing, training, users, groups, reporting) followed by singular/plural resource nouns and consistent verbs (list, get, members). The only minor deviation is the utility tools (navigate, back, status) which break the pattern but are intentional.
30 tools is on the heavy side, but KnowBe4 is a broad platform covering phishing, training, users, groups, reporting, and account data. Each tool covers a genuinely distinct resource that an agent would query. It leans toward the upper edge of reasonable scope, though several reporting summary tools aggregate data that could be computed from existing list tools, suggesting some redundancy.
The surface covers the primary KnowBe4 domains well: phishing campaigns/tests/recipients, training, users, groups, store purchases, and policies. However, the toolset is entirely read-only — there are no create, update, or delete tools for any resource, which means agents cannot trigger phishing simulations, enroll users, or modify campaigns. This limits it to a querying/analysis server.
Maintenance
Related MCP Connectors
Hosted MCP servers for MSP tools: ConnectWise, NinjaOne, Microsoft 365, SentinelOne, Pax8 and more.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
isolved and ApplicantPro jobs, tenant discovery, and change detection as an MCP server.
MEOK MCP Hardening MCP — automated security red-team for any MCP server. Maps OWASP LLM Top 10
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceMCP server for Huntress API integration1MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server for the NinjaOne RMM platform, enabling tools to manage devices, organizations, alerts, jobs, and policies through NinjaOne's API.32Apache 2.0
- AlicenseAqualityBmaintenanceMCP server for Checkpoint Harmony Email & Collaboration (Avanan). Enables AI assistants to manage email security, anti-phishing, anti-malware, and threat detection via the Avanan API.131Apache 2.0
- AlicenseAqualityCmaintenanceMCP server for Ironscales — phishing incident management, email classification, and remediation2Apache 2.0