用于KnowBe4 GraphQL API的MCP服务器

版本： 1.0.0

发布日期： 2025-10-14

作者田裕角

生产状态： ✅ 已准备好供本地使用

以安全为重点的模型上下文协议（MCP）服务器，为Claude Desktop提供对KnowBe4 GraphQL API的安全、只读访问。

🏠 部署模型： 这是一个 本地桌面工具 专为Claude Desktop个人使用而设计。不适用于云或多租户部署。

概述

只读GraphQL查询执行
92+预优化查询，带缓存
智能查询路由器模式匹配成功率86%
交互式查询发现，澄清问题
多策略PII字段过滤和隐私控制
全面的审计和对话记录
查询复杂性验证（150行限制）
安全性突变阻断
速率限制（100个查询/60秒）
查询大小限制（最大100KB）

快速开始

先决条件

Python 3.10或更高版本
KnowBe4钻石级账户
KnowBe4产品API密钥
Claude桌面应用程序

安装

安装依赖项

   pip install -r setup/requirements.txt

配置环境

   cp config/.env.example .env

编辑 .env 并设置：

- GRAPHQL_ENDPOINT -您的KnowBe4 GraphQL端点（见下面的区域） - GRAPHQL_API_KEY -来自合作伙伴设置的KnowBe4产品API密钥

下载GraphQL架构

该架构是必需的，但出于安全考虑，未包含在存储库中。

快速方法：

   python setup/download_schema.py

手动方法： 看 docs/SETUP_SCHEMA.md 详细说明。

测试服务器

   python mcp-server/main.py

您应该看到： Server initialized successfully 按Ctrl+C停止。

配置Claude桌面

找到您的Claude Desktop配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

添加此服务器配置 （参见 config/claude_desktop_config.json.example):

{
  "mcpServers": {
    "knowbe4-graphql": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-server-knowbe4-graphql-api/mcp-server/main.py"],
      "env": {
        "GRAPHQL_ENDPOINT": "https://training.knowbe4.com/graphql",
        "GRAPHQL_API_KEY": "your_api_key_here",
        "GRAPHQL_SCHEMA_PATH": "/absolute/path/to/mcp-server-knowbe4-graphql-api/config/schema.json"
      },
      "alwaysAllow": ["*"]
    }
  }
}

重要提示： 使用绝对路径，而不是相对路径。

自动批准工具（可选但推荐）

默认情况下，Claude Desktop会在执行每个工具之前要求确认。为避免重复的确认提示，请添加 alwaysAllow 配置：

选项1：批准所有工具（最简单）

"alwaysAllow": ["*"]

选项2：批准特定工具

"alwaysAllow": [
  "query_graphql",
  "get_quick_query",
  "get_schema_info",
  "list_quick_queries",
  "discover_queries",
  "suggest_query_for_question",
  "auto_answer",
  "get_server_status",
  "clear_cache"
]

这是 此MCP服务器安全 因为：

✅ 所有操作都是只读的（不允许突变）
✅ 无文件系统写入或危险操作
✅ 内置安全控制（PII过滤、速率限制、查询验证）
✅ 仅供本地桌面使用

重新启动克劳德桌面 加载MCP服务器。

克劳德测试

在Claude Desktop中，尝试：

“你能检查KnowBe4 GraphQL服务器的状态吗？”

克劳德应该用 get_server_status 工具。

然后尝试：

“谁是我风险最高的用户？”

克劳德将使用 get_quick_query 快速获取此数据的工具。

KnowBe4区域终点

为您的地区选择合适的端点：

区域	端点
美国	`https://training.knowbe4.com/graphql`
欧洲	`https://eu.knowbe4.com/graphql`
加拿大	`https://ca.knowbe4.com/graphql`
联合王国	`https://uk.knowbe4.com/graphql`
德国	`https://de.knowbe4.com/graphql`

可用的MCP工具

查询执行

`query_graphql(query, variables)`

执行自定义只读GraphQL查询。

query_graphql(
    query="""
    query GetUsers {
        users(first: 10) {
            nodes { id firstName lastName }
        }
    }
    """
)

`get_quick_query(query_name, variables, use_cache)`

执行预先优化的查询（更快，缓存）。

# Get tenant info (cached for 5 min)
get_quick_query(query_name="TENANT_INFO")

# Find user by name
get_quick_query(
    query_name="FIND_USER_TEMPLATE",
    variables={"searchTerm": "John"}
)

`list_quick_queries()`

列出所有可用的预优化查询。

`discover_queries(topic)` 新

发现某个主题的可用查询，并获得澄清问题。

当用户提出诸如“向我展示培训内容”之类的模糊请求时，此工具可以帮助Claude了解可用的内容，并提出澄清问题以缩小请求范围。

# User says: "Show me training stuff"
discover_queries(topic="training")
# Returns: Available training queries and suggested clarifying questions

# Supported topics:
# - training, users, security, phishing, dashboard, groups
# - audit, templates, enrollments, account

它如何帮助：

防止错误的查询选择
通过澄清问题改善用户体验
使模糊的请求更加精确
显示主题的所有可用选项

`suggest_query_for_question(user_question)` 新&智能

自动分析用户问题，并建议使用最佳查询。

使用模式匹配可以立即识别86%常见问题的正确查询，消除了反复试验。

# User asks: "Which managers haven't completed their training?"
suggest_query_for_question("Which managers haven't completed their training?")
# Returns:
# {
#   "suggested_query": "INCOMPLETE_ENROLLMENTS_TEMPLATE",
#   "confidence": "high",
#   "variables_needed": ["campaignId"],
#   "workflow": ["1. Get campaigns", "2. Find campaign ID", "3. Use template"],
#   "fallback_queries": [...]
# }

优点：

86%的模式匹配成功率 常见问题解答
具有置信度的即时查询建议
复杂查询的分步工作流程
如果主查询不起作用，则提供回退建议
将9个查询减少到1-2个查询（减少78-89%）

配置

get_schema_info() -获取架构元数据和安全设置
get_schema_type_info(type_name) - 新查找任何GraphQL类型的正确字段名
get_server_status() -检查服务器运行状况、配置和缓存统计信息
set_pii_mode(enabled) -切换PII字段访问（默认禁用）
add_blocked_field(field_name) -添加自定义字段阻止
remove_blocked_field(field_name) -从阻止列表中删除字段

演出

clear_cache(query_name) -清除查询缓存（全部或特定查询）

预优化查询

92+按类别组织的即用型查询：

账户和租户：

TENANT_INFO -全面的租户/账户信息
SECURITY_SETTINGS -帐户安全设置

用户管理：

ACTIVE_USER_COUNT -活跃用户数
ALL_ACTIVE_USERS -列出所有活动用户
HIGH_RISK_USERS -风险评分最高的用户
FIND_USER_TEMPLATE -按搜索词查找用户（需要 searchTerm)
USER_DETAILS_TEMPLATE -详细的用户信息（必填 userId)

活动：

ACTIVE_PHISHING_CAMPAIGNS -活跃的网络钓鱼活动
ACTIVE_TRAINING_CAMPAIGNS -积极的培训活动
LOW_COMPLETION_TRAINING -带有完成统计数据的培训

报名人数：

INCOMPLETE_ENROLLMENTS_TEMPLATE -注册不完整（必填 campaignId)
USER_ENROLLMENTS_TEMPLATE -用户注册（需要 userId)

团体和风险：

ALL_GROUPS -列出所有组
GROUPS_WITH_RISK_SCORES -有风险数据的群体
ORGANIZATION_RISK_SCORE -全组织风险指标
INDUSTRY_BENCHMARKS -与行业基准进行比较

审计：

RECENT_AUDIT_LOGS -最近的审计条目（过去7天）

看 QUERY_LIBRARY_USAGE.md 以获取完整的文档。

安全与隐私（本地桌面工具）

安全设计：

✅ 使用Claude Desktop在您的计算机上本地运行
✅ 只读操作（阻止所有突变）
✅ 多策略PII字段过滤
✅ 速率限制（100个查询/60秒）
✅ 全面的审计日志记录（本地文件）
✅ API密钥安全存储在 .env （忽略）
✅ 无遥测或外部数据传输（KnowBe4 API除外）

隐私：

✅ 默认情况下禁用对话日志记录
✅ 审计日志中散列的所有敏感数据
✅ 本地存储在计算机上的日志
✅ 进程隔离（每个Claude Desktop实例=单独的进程）

______________________________________________________________________

安全功能

PII最小化

默认情况下，包含PII字段的查询被阻止：

电子邮件，电子邮件地址
电话号码，电话
地址，街道地址
出生日期、社会保障号码、护照
信用卡、银行账户

仅在必要时启用PII模式： set_pii_mode(true)

只读执行

所有突变都在查询验证级别被阻止。

查询复杂性限制

查询限制为150行，以符合KnowBe4 API的限制。

审计日志

所有查询都记录到 logs/audit/audit_YYYYMMDD.jsonl 与：

时间戳和会话ID
查询哈希和预览
响应哈希和大小
持续时间和状态
PII模式状态

日志采用JSON Lines格式，便于SIEM集成。

对话记录

用户交互记录到 logs/conversation/conversations_YYYYMMDD.jsonl 与：

完整的对话流程
原始用户问题（通过提供时 user_question 参数）
完整的响应内容 （完整答案供分析）
处理步骤和工具调用
性能指标
成功/错误跟踪

这 query_graphql 和 get_quick_query 工具接受可选 user_question 参数，以捕获原始用户的问题，从而进行更好的分析。这有助于跟踪用户实际询问的内容以及系统如何解释它。

隐私说明： 对话日志存储完整的响应（而不仅仅是哈希），以便进行全面分析。确保日志通过适当的访问控制和保留策略安全存储。

使用这些日志进行数据驱动的改进。看分析_日志.md 用于分析指南。

性能和缓存

缓存策略

缓存（5分钟）： 非参数化查询（TENANT_INFO、ALL_GROUPS等）
未缓存： 参数化查询（用户搜索、特定ID）
自动失效： 缓存将在5分钟后过期

缓存命中率

查询类型	首次运行	后续运行
TENANT_INFO	1-2s	\<100ms（缓存）
HIGH_RISK_USER	2-3s	\<100ms（缓存）
全部_组	1-2s	\<100ms（缓存）

何时清除缓存

# After making changes via KnowBe4 UI
clear_cache(query_name="ALL_USERS")

# After bulk user import
clear_cache()  # Clear all

# Before critical reports
get_quick_query(query_name="TENANT_INFO", use_cache=False)

故障排除

服务器未出现在Claude桌面中

检查配置路径：

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

验证路径是否为绝对路径 在配置文件中

重新启动克劳德桌面 在任何配置更改之后

检查克劳德日志：

   tail -f ~/Library/Logs/Claude/mcp-server-knowbe4-graphql.log

常见错误

“找不到架构文件”

下载GraphQL模式并另存为 schema.json

“GRAPHQL_API_KEY环境变量是必需的”

检查你的 .env 文件或ClaudeDesktop配置具有API密钥集

“查询超出复杂性限制”

将查询减少到150行或更少
删除不必要的字段或使用分页

“不允许突变”

此服务器是只读的；为了安全起见，突变被阻断

“查询包含被阻止的PII字段”

PII模式默认禁用
让Claude启用PII模式或删除特定字段

“类型上不存在字段”

GraphQL字段名猜错了
使用 get_schema_type_info(type_name) 查找正确的字段名称
例子： get_schema_type_info("PhishingCampaign") 显示所有可用字段
提示： Claude在编写自定义查询之前应该始终检查模式

权限问题

如果您遇到权限错误：

   mkdir -p logs/audit logs/conversation && touch logs/audit/test && rm logs/audit/test && echo "OK"

检查OneDrive同步 使用同步文件夹时的状态

使用非同步目录 通过在中设置绝对路径来获得更好的性能 .env:

   AUDIT_LOG_DIR=/var/log/knowbe4/audit
   CONVERSATION_LOG_DIR=/var/log/knowbe4/conversation

日志记录问题

日志未出现或转到错误的目录：

检查.env配置：

   grep LOG_DIR .env

应显示：

   AUDIT_LOG_DIR=logs/audit
   CONVERSATION_LOG_DIR=logs/conversation

重新启动克劳德桌面 变更后 .env -服务器仅在启动时加载环境变量

   ls -la logs/audit logs/conversation

验证日志是否正在立即写入：

- 每次操作后日志同步写入磁盘 - 如果日志仅在关闭Claude Desktop后出现，请确保在最新更新后重新启动

出现在多个目录中的日志：

旧登录 audit_logs/ 确认有新日志后可以安全删除 logs/audit/
服务器现在可以正确使用配置的目录路径

检查日志

审核日志：

cat logs/audit/audit_$(date +%Y%m%d).jsonl

对话日志：

cat logs/conversation/conversations_$(date +%Y%m%d).jsonl | jq .

Claude Desktop日志（用于服务器错误）：

tail -f ~/Library/Logs/Claude/mcp-server-knowbe4-graphql.log

项目结构

.
├── README.md                # This file
├── CLAUDE.md                # Architecture and technical reference
├── .env                     # Environment variables (not committed)
├── mcp-server/              # MCP server application
│   ├── main.py              # Server entry point
│   ├── graphql_tools.py     # GraphQL execution and validation
│   ├── audit_logger.py      # Compliance logging
│   ├── conversation_logger.py  # User interaction tracking
│   └── query_library.py     # Pre-optimized queries and caching
├── docs/                    # Documentation
│   ├── QUERY_LIBRARY_USAGE.md   # Complete query documentation
│   └── ANALYZING_LOGS.md    # Log analysis guide
├── config/                  # Configuration files
│   ├── .env.example         # Environment template
│   ├── claude_desktop_config.json.example  # Claude Desktop config template
│   ├── mcp.json             # MCP config example
│   ├── schema.json          # KnowBe4 GraphQL schema (user-provided, not in git)
│   └── schema.json.example  # Schema download instructions
├── setup/                   # Setup and initialization
│   ├── requirements.txt     # Python dependencies
│   ├── pyproject.toml       # Project metadata
│   └── download_schema.py   # Schema download helper
└── tests/                   # Test files
    ├── conftest.py          # Pytest fixtures
    ├── test_*.py            # Unit test suites
    └── diagnose.py          # Diagnostic tool

发展

运行测试

# Run all unit tests
pytest

# Run tests with coverage
pytest --cov=. --cov-report=html

# Run diagnostics
python3 tests/diagnose.py

代码格式化

black .

代码检查

ruff check .

合规

此服务器旨在满足：

SOC 2审计要求
ISO 27001安全标准
内部安全政策

功能包括：

会话范围的秘密（无持久存储）
全面的审计跟踪
现场级访问控制
查询验证和清理

文档

核心文档（根文件夹）

README.md -此文件（主要文档、快速入门、使用指南）
CLAUDE.md -架构、技术参考和开发指南（适用于Claude Code）
更改日志.md -版本历史和已完成的改进
许可证.md -MIT许可证和版权信息

详细指南（文档/文件夹）

设置和配置：

docs/SETUP_SCHEMA.md -GraphQL模式下载说明
docs/DEPENDENCIES.md -依赖关系管理和安全更新

用法与参考：

docs/QUERY_LIBRARY_USAGE.md -包含92多个预优化查询的完整查询库参考
docs/FIELD_REFERENCE.md -KnowBe4 GraphQL字段引用和常见模式
docs/ANALYZING_LOGS.md -日志分析和改进指南

发展：

docs/TEST.md -测试指南（另见：测试/README.md 综合指南）
docs/REPOSITORY_STRUCTURE.md -项目结构和代码组织

安全：

docs/SECURITY_REVIEW.md -全面的安全分析和控制

参考文献

许可证

MIT许可证-有关详细信息，请参阅许可证文件

警告

此服务器需要KnowBe4钻石级帐户。KnowBe4对API的支持有限。通过API删除（如果启用了突变）是永久性的，无法撤消。

Knowbe4 Graphql API

快速接入

详细介绍