KnowBe4 Server

A Model Context Protocol (MCP) server for the KnowBe4 Reporting REST API. This server enables AI assistants to interact with your KnowBe4 security awareness training platform data.

Created by Mirage Security

Features

This MCP server provides access to all KnowBe4 Reporting API endpoints:

Account

• Get account and subscription data
• Get account risk score history

Users

• List all users (with filtering by status, group)
• Get specific user details
• Get users in a specific group
• Get user risk score history

Groups

• List all groups
• Get specific group details
• Get group risk score history

Phishing

• Get phishing campaigns
• Get phishing security tests (PSTs)
• Get PST recipient results
• Get specific recipient details

Training

• Get store purchases
• Get policies
• Get training campaigns
• Get training enrollments

Prerequisites

• Node.js 18 or higher
• A KnowBe4 account with Platinum or Diamond subscription
• KnowBe4 API key (available in your Account Settings)

Installation

You can run the server with npx (no local install) or clone and build it yourself. Most users should pick one of the npx forms — see Usage with Claude Desktop for the matching config snippets.

Form	When to use
npx -y knowbe4-mcp-server	Default: pulls the published package from npm. Recommended for end users.
npx -y github:<owner>/knowbe4-mcp-server	When you need an unreleased change, a fork, or a specific branch.
Clone + npm run build	When you're developing the server itself.

From source (for development)

1. Clone or download this repository
2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

The prepare lifecycle script also runs npm run build automatically when the package is installed from a Git source, so npx github:... works without a manual build step.

Configuration

Getting Your API Key

1. Log in to your KnowBe4 console
2. Navigate to Account Settings
3. Find the API section
4. Copy your API key or generate a new one if needed

Important: Keep your API key secure and do not share it publicly.

Environment Variables

The server requires the following environment variables:

• KNOWBE4_API_KEY (required): Your KnowBe4 API key
• KNOWBE4_REGION (optional): Your server region - us, eu, ca, uk, or de (default: us)

Determine your region based on your KnowBe4 login URL:

• US: training.knowbe4.com → use us
• EU: eu.knowbe4.com → use eu
• CA: ca.knowbe4.com → use ca
• UK: uk.knowbe4.com → use uk
• DE: de.knowbe4.com → use de

Usage with Claude Desktop

Add this server to your Claude Desktop configuration file:

macOS

Edit: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Edit: %APPDATA%\Claude\claude_desktop_config.json

Pick one of the three forms below.

Option A: npx from the npm registry (recommended)

Zero install — npx fetches the published package on first launch and caches it. The -y flag is required so npx doesn't prompt for confirmation, which would corrupt the MCP stdio handshake.

{
  "mcpServers": {
    "knowbe4": {
      "command": "npx",
      "args": ["-y", "knowbe4-mcp-server"],
      "env": {
        "KNOWBE4_API_KEY": "your-api-key-here",
        "KNOWBE4_REGION": "us"
      }
    }
  }
}

Once you've confirmed it works, pin the version for reproducibility: "[email protected]" (or whichever version you tested). On Windows, use "command": "npx.cmd" if npx fails to launch from Claude Desktop.

Option B: npx from a Git source

Use this to run an unreleased change, a fork, or a specific branch. npm clones the repo and the prepare script builds it on install — no manual npm run build needed.

{
  "mcpServers": {
    "knowbe4": {
      "command": "npx",
      "args": ["-y", "github:mirage-security/knowbe4-mcp-server"],
      "env": {
        "KNOWBE4_API_KEY": "your-api-key-here",
        "KNOWBE4_REGION": "us"
      }
    }
  }
}

Replace the github: target with github:<owner>/<repo>#<branch> to pin to a fork or branch.

Option C: local build

If you cloned and built the repo yourself (see From source):

{
  "mcpServers": {
    "knowbe4": {
      "command": "node",
      "args": ["/absolute/path/to/knowbe4-mcp-server/build/src/index.js"],
      "env": {
        "KNOWBE4_API_KEY": "your-api-key-here",
        "KNOWBE4_REGION": "us"
      }
    }
  }
}

Replace:

• /absolute/path/to/knowbe4-mcp-server with the actual path to this project
• your-api-key-here with your actual KnowBe4 API key
• us with your region if different

Available Tools

Once configured, Claude will have access to these tools:

Account Tools

• get_account - Get account and subscription information
• get_account_risk_score_history - Get historical risk scores

User Tools

• get_users - List all users with optional filters
• get_user - Get specific user by ID
• get_group_members - Get users in a group
• get_user_risk_score_history - Get user risk score history

Group Tools

• get_groups - List all groups
• get_group - Get specific group
• get_group_risk_score_history - Get group risk score history

Phishing Tools

• get_phishing_campaigns - List all phishing campaigns
• get_phishing_campaign - Get phishing campaign details
• get_phishing_security_tests - List all PSTs
• get_campaign_security_tests - Get PSTs from specific campaign
• get_phishing_security_test - Get specific PST
• get_pst_recipients - Get recipient results for PST
• get_pst_recipient - Get specific recipient result

Training Tools

• get_store_purchases - List store purchases
• get_store_purchase - Get specific store purchase
• get_policies - List policies
• get_policy - Get specific policy
• get_training_campaigns - List training campaigns
• get_training_campaign - Get specific training campaign
• get_training_enrollments - List training enrollments
• get_training_enrollment - Get specific enrollment

Example Prompts

Once configured, you can ask Claude things like:

• "What is my organization's current risk score?"
• "Show me all active users in my account"
• "Get the results from phishing security test ID 12345"
• "List all training campaigns"
• "Show me users with the highest phish-prone percentage"
• "Get all groups and their current risk scores"

API Rate Limits

KnowBe4 API has the following limits:

• 2,000 requests per day plus the number of licensed users
• Maximum 4 requests per second
• Burst limit of 50 requests per minute

Pagination

Most list endpoints support pagination with these parameters:

• page - Page number (default: 1)
• per_page - Results per page (default: 100, max: 500)

The server automatically handles these parameters for you.

Development

Watch Mode

Run TypeScript compiler in watch mode:

npm run watch

Testing

The project includes comprehensive integration tests using Node.js built-in test runner.

Run all tests:

KNOWBE4_API_KEY=your-key npm test

Run tests in watch mode:

KNOWBE4_API_KEY=your-key npm run test:watch

Test Coverage:

• 30 integration tests across 5 endpoint categories
• Account endpoints (3 tests)
• User endpoints (5 tests)
• Group endpoints (5 tests)
• Phishing endpoints (8 tests)
• Training endpoints (9 tests)

Tests make real API calls and validate response structure and data. See tests/README.md for detailed testing documentation.

Security Notes

• Never commit your API key to version control
• Store your API key securely
• Use environment variables for configuration
• KnowBe4 API keys provide access to sensitive security training data
• Anonymous accounts cannot retrieve anonymized data

Troubleshooting

"KNOWBE4_API_KEY environment variable is required"

Make sure you've set the KNOWBE4_API_KEY in your Claude Desktop config.

"401 Unauthorized"

Your API key is incorrect or expired. Generate a new one in KnowBe4 Account Settings.

"404 Not Found"

Check that you're using the correct region for your account.

"429 Too Many Requests"

You've exceeded the rate limit. Wait before making more requests.

About

This MCP server was created by Mirage Security to enable seamless integration between AI assistants and the KnowBe4 security awareness training platform.

License

MIT

Resources

• KnowBe4 API Documentation
• Model Context Protocol
• Claude Desktop