Skip to main content
Glama

KnowBe4 MCP Server

License Node.js

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-mcp

Related MCP server: ninjaone-mcp

Configuration

Copy .env.example. Stdio and AUTH_MODE=env read the KnowBe4 variables. Gateway mode does not.

Variable

Required

Description

KNOWBE4_API_KEY

For stdio and AUTH_MODE=env

KnowBe4 API key

KNOWBE4_REGION

No

API region: us (default), eu, ca, uk, or de

KNOWBE4_BASE_URL

No

Custom base URL (overrides region)

MCP_TRANSPORT

No

stdio (default) or http

AUTH_MODE

No

env (default outside the image) or gateway. The container image and Compose default to gateway. Gateway mode requires X-KnowBe4-API-Key on each /mcp request (X-KnowBe4-Region is optional) and never falls back to KNOWBE4_*.

CONDUIT_S2S_SECRET

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 openssl rand -hex 32.

MCP_ALLOW_INSECURE_DEV

No

Set to 1 only for local development to start HTTP without CONDUIT_S2S_SECRET. The process logs a warning, does not enforce X-Gateway-S2S, and binds 127.0.0.1 only. A non-loopback MCP_HTTP_HOST refuses startup. A known placeholder secret is still refused.

MCP_HTTP_HOST

No

Bind address when a real CONDUIT_S2S_SECRET is set. Unset keeps 0.0.0.0, which is what the container image sets, so container deploys stay on every interface inside the container. Without a secret the dev bypass binds 127.0.0.1 instead.

MCP_HTTP_PORT

No

HTTP port. Defaults to 8080.

/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-mcp

Docker

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-mcp

Compose 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 up

Single-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-mcp

Local 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 start

Available 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 test

Contributing

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 tools
knowbe4_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_navigateA

Discover available KnowBe4 tools by domain. Returns tool names and descriptions for the selected domain. All tools are callable at any time — this is a help/discovery aid, not a prerequisite.

Inputs: domain (required).

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

    B3.4/5.0

    Scored across 30 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server for the NinjaOne RMM platform, enabling tools to manage devices, organizations, alerts, jobs, and policies through NinjaOne's API.
      32
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      13
      1
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Ironscales — phishing incident management, email classification, and remediation
      2
      Apache 2.0