knowbe4-mcp

A read-only Model Context Protocol (MCP) server for KnowBe4 security awareness training, by WIT-SecOps. It gives AI assistants a partner-wide view of every client account (seats, phish-prone percentage, risk score, training coverage) and per-user risk figures. Per-client phishing and training detail comes from each client's Reporting API.

Note: Not affiliated with or endorsed by KnowBe4, Inc.

Features

• 17 read-only tools: accounts, users and a portfolio overview for every client from one partner key; groups, risk history, phishing tests (down to who clicked) and training enrollments for each client with a Reporting key; and four combined tools: a QBR scorecard, at-risk users, training gaps, and an onboarding check against the Deployment runbook
• Multi-client by design: every tool works on exactly one named account; only the portfolio overview spans clients, and it shows account-level totals only
• Privacy-first defaults: user rows carry only id, name, email, department, phish-prone % and risk score. Phone numbers, manager, location, employee number, sign-in IP and console admins need include_sensitive: true
• Secret fields are never selected: the partner schema exposes API tokens, LDAP and PST tokens on the same types this server reads. Every query uses a fixed field allowlist, pinned by tests
• No write tools, no persistence: data lives in memory for at most 10 minutes, and the audit log on stderr records tool, account and row count, never payloads
• Client-side pacing for each client's Reporting API limits (4 per second, 50 per minute)
• Markdown and JSON response formats
• All KnowBe4 regions (US, EU, CA, UK, DE)
• Runs locally over stdio; each MCP client spawns its own process

Quick Start

Step-by-step instructions, including creating the keys, are in docs/KnowBe4-MCP-Setup-Guide.html.

The server reads its keys only from its environment. It never reads a key file, and keys are never accepted on the command line.

Claude Desktop, with the Kryptos vault

1. Store the keys in Kryptos, in your own terminal. Each command asks for the value with hidden typing:

   kryptos set KNOWBE4_PARTNER_TOKEN --note "KnowBe4 partner key"
   kryptos set KNOWBE4_TOKEN_WIT --note "KnowBe4 Reporting key, Winona IT"

2. Open Claude Desktop and go to Settings > Developer > Edit Config, then add the following to claude_desktop_config.json:

   {
     "mcpServers": {
       "knowbe4": {
         "command": "kryptos",
         "args": ["run", "--only", "KNOWBE4_*", "--", "npx", "-y", "@wit-secops/knowbe4-mcp"]
       }
     }
   }

   Kryptos starts the server with only the KNOWBE4_* secrets in its environment. No key goes in the config.

3. Save the file and restart Claude Desktop.

On the Microsoft Store build of Claude Desktop, the file is under %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\, not %APPDATA%\Claude\. Edit Config always opens the right one.

Without Kryptos

Set the same variables in the process environment (containers, CI). A KNOWBE4_* variable that isn't a key or setting the server reads is reported by name at startup, which catches a key stored under the wrong name.

Other MCP Clients (Cursor, Windsurf, Claude Code, etc.)

Most MCP clients use the same stdio configuration format shown above.

Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | KNOWBE4_PARTNER_TOKEN | Partner API key: every client, account and user level | At least one key | | | KNOWBE4_TOKEN_<ALIAS> | One client's Reporting API key. <ALIAS> is the client's IT Glue short name, e.g. KNOWBE4_TOKEN_WIT | No | | | KNOWBE4_REGION | us, eu, ca, uk or de | No | us | | KNOWBE4_BASE_URL | Reporting API base URL (overrides the region) | No | https://us.api.knowbe4.com | | KNOWBE4_GRAPH_URL | Partner GraphQL URL (overrides the region) | No | https://training.knowbe4.com/graphql |

CLI Options

--region <region>       KnowBe4 region: us, eu, ca, uk, de (default: us)
--base-url <url>        Reporting API base URL (overrides --region)
--graph-url <url>       Partner GraphQL URL (overrides --region)
--read-only             Accepted for consistency; the server is always read-only
--help, -h              Show help
--version, -v           Show version

Keys are never accepted on the command line, where they would show in process listings.

Access

This version is read-only: it registers no tool that can change anything in KnowBe4. The tools are annotated readOnlyHint: true.

Read-only is not a security boundary on its own. The real control is who receives the keys: the partner key reads every client's user data. Hand it only to SecOps staff who need it.

Tools

Combined tools (start here)

| Tool | Keys | Description | |------|------|-------------| | kb4_client_scorecard | either | QBR one-pager: users vs. seats, phish-prone %, risk score and its six-month trend, training coverage, phishing results since a date (click and report rates, delivery warnings) and training status. Aggregates only. Without a Reporting key it shows the account figures and says what's missing | | kb4_at_risk_users | Reporting | Active users ranked by phishing-test failures over a period, with failure events, outstanding training, risk score, and "repeat" / "untrained" flags. For coaching | | kb4_training_gaps | Reporting | Active users with past-due, not-started or in-progress training, and users never enrolled | | kb4_onboarding_check | Reporting | The KnowBe4 Deployment runbook as PASS/WARN/FAIL: SCIM sync, users vs. seats, the "KnowBe4 Users" synced group, the "New Employees" smart group, the "New Employee Onboarding" campaign, a phishing campaign, and phishing delivery health (the stand-in for Microsoft 365 allowlisting) |

Portfolio and accounts (partner key)

| Tool | Description | |------|-------------| | kb4_portfolio_overview | Headline figures for every client (users vs. seats, phish-prone %, last-test phish-prone %, risk score, % trained, Reporting API status) plus user-weighted totals and over-seat clients | | kb4_list_accounts | List client accounts with headline figures; shows which have a Reporting key configured | | kb4_get_account | One client's profile: seats, risk and training figures, console configuration (SAML, smart groups, Phish Alert Button, MFA), API access, SKUs. Console admins with include_sensitive |

Users (partner key)

| Tool | Description | |------|-------------| | kb4_list_users | One client's users with phish-prone % and risk score, riskiest first; group_id lists a group's members | | kb4_get_user | One user's profile: phish-prone %, risk score, groups, MFA, join and last sign-in dates. Sensitive fields with include_sensitive |

Groups and risk (client Reporting key)

| Tool | Description | |------|-------------| | kb4_list_groups | Groups with type (synced from the directory via SCIM or AD, smart, or console), member count and risk score | | kb4_get_risk_history | Risk score trend for the account, a group or a user: latest, change, range and a monthly table |

Phishing (client Reporting key)

| Tool | Description | |------|-------------| | kb4_list_phishing_campaigns | Campaigns with status, frequency, groups, last run, last phish-prone % and test count | | kb4_list_security_tests | Tests with template, phish-prone % and full result counts, plus delivery warnings (bounces, undelivered, no opens) that point to allowlisting problems | | kb4_get_pst_results | One test's summary and recipients: who failed (default), reported or bounced. IP, location, browser and OS with include_sensitive |

Training (client Reporting key)

| Tool | Description | |------|-------------| | kb4_list_training_campaigns | Campaigns with status, groups, content, dates, time allowed and auto-enrolment | | kb4_list_enrollments | Who is assigned what, with a status breakdown; filter to past_due or incomplete. Employee numbers with include_sensitive | | kb4_list_training_content | Store purchases and uploaded policies |

The Reporting tools are registered only when at least one client key is configured. For a client without a key, they return an error explaining how to create one.

The account argument

Every per-client tool takes account, which can be:

• a Reporting key alias (WIT)
• a KnowBe4 account ID (123456)
• a domain (example.com)
• a name: an exact match, else a unique case-insensitive substring

An ambiguous name is an error that lists the candidates; the server never guesses. With only one account available, account can be omitted.

Filter semantics

• Applied by the KnowBe4 API (exact): status and group_id on kb4_list_users; status on kb4_list_groups; campaign_id on kb4_list_security_tests; campaign_id, user_id and include_archived_users on kb4_list_enrollments.
• Everything else (filter_name, filter_department, kind, since, with_warnings, outcome, enrollment status) is matched locally over the full list. Name filters are case-insensitive substrings.
• Sorting and paging are local, over the full list, so totals are exact.

Keys

Partner key

Create it in the API section of KnowBe4 Partner Settings (training.knowbe4.com/ui/management/account/info on US), with read-only access. It covers the partner GraphQL API for every client account. It does not work on the Reporting API.

Client Reporting keys

Each client's phishing-test results, recipients and training enrollments are only available through that client's own Reporting API key. There is no partner-wide Reporting key. In the client console (View as Admin): Account Settings → Account Integrations → API → Enable Reporting API Access → Create New API Token. The Reporting API needs a Platinum, Diamond, SAT Foundation or SAT Advanced subscription.

Name the environment variable after the client's IT Glue short name (KNOWBE4_TOKEN_WIT). The server matches each key to its partner account by domain, so no account IDs need configuring.

Regions

| Region | Reporting API | Partner GraphQL | |--------|---------------|-----------------| | us | https://us.api.knowbe4.com | https://training.knowbe4.com/graphql | | eu | https://eu.api.knowbe4.com | https://eu.knowbe4.com/graphql | | ca | https://ca.api.knowbe4.com | https://ca.knowbe4.com/graphql | | uk | https://uk.api.knowbe4.com | https://uk.knowbe4.com/graphql | | de | https://de.api.knowbe4.com | https://de.knowbe4.com/graphql |

Rate Limits

KnowBe4 limits each client's Reporting API to 4 requests per second, 50 per minute, and 2,000 plus the licensed-user count per day. The server paces every client key to stay under the per-second and per-minute limits. Interactive tools don't retry a 429; they fail fast with a clear message.

Risk scores are recalculated daily, so figures can be up to 24 hours old.

Privacy and Terms

• Use this data for security-awareness coaching and reporting, not HR discipline.
• KnowBe4's API terms allow internal use only and require compliance with privacy law. Don't host this server for clients or third parties.

Development

npm install
git config core.hooksPath .githooks
npm run check

npm run check runs lint, format:check, build and test. Checks run locally, not in GitHub Actions: the pre-push hook in .githooks/ runs npm run check before every push. The only workflow, publish.yml, publishes to npm when a GitHub Release is published.

npm run dev runs the server from source with tsx watch.

License

MIT