Keycloak MCP Server

Keycloak MCP 服务

一个用于 Keycloak 管理的 Model Context Protocol（MCP）服务。它可让 Claude 等 AI 助手通过 Keycloak Admin REST API 管理用户、组、角色和会话，并检查客户端、事件以及领域的安全状况，同时采用最小权限身份验证，并为每项写入操作设置防护措施。

警告

此服务所执行的操作权限与您提供的 Keycloak 账户相同。请使用仅分配所需角色的专用服务账户客户端，切勿使用引导管理员账户。默认情况下，每个会更改数据的工具都会要求确认，并且提供只读模式。请参阅安全性。

亮点

• 7 个工具集共 24 个工具，可按工具集启用。默认工具集（core、groups、roles）规模小，其余工具集均为可选。
• 最小权限身份验证。 推荐使用带服务账户的 client_credentials 授权方式；也可使用密码授权方式。不设默认凭据，因此缺少设置时会立即报错。
• 防护措施。 只读模式、领域允许列表、禁止写入 master 领域，以及每次更改都必须先预览、再通过 confirm: true 确认。系统会通过组合角色和父组检测管理员权限授予。
• 4 个引导式提示词（入职、离职、安全审计、登录失败调查）以及用于领域和用户的 MCP 资源，并支持自动补全领域名称。
• 结构化分页输出，带有输出架构；绝不返回或记录机密和凭据。
• 适用于 Claude Desktop、Claude Code、VS Code、Cursor 以及任何 stdio MCP 客户端。需要 Node.js 22 或更高版本。

工作原理

MCP 客户端会将服务作为本地子进程启动，并通过 stdio 与其通信。每次工具调用都会通过防护检查，然后交由统一网关处理 Keycloak 登录并缓存访问令牌。

已确认的调用示例

每个会更改数据的工具都是 破坏性 操作（会删除或撤销数据），或 敏感 操作（会更改身份、凭据、权限或保护机制，例如 user_update 或 user_role_assign）。如果未使用 confirm: true 调用，此类工具只会返回操作预览，不会进行任何更改。获得批准后，助手会再次使用 confirm: true 发起调用。

模型本身也可以设置 confirm: true，即使是首次调用也可以。此时服务仍会计算预览，并将其与结果一并返回，但只有客户端的批准提示才能证明有人类同意。所有此类工具都带有 destructiveHint，因此会在破坏性调用前征求确认的客户端，也会在这里征求确认。

快速开始

要求： Node.js 22 或更高版本、您的机器能够访问的 Keycloak 服务（已在 Keycloak 24.0 到 26.8 上测试），以及一个 MCP 客户端。

1. 准备 Keycloak（3 步）

在要管理的 realm 中（此处为 demo）：

1. 创建客户端 mcp-admin，开启 Client authentication，并且只启用 Service accounts roles（关闭 Standard flow 和 Direct access grants）。
2. 分配角色。 在客户端的 Service accounts roles 选项卡中，分配 realm-management 的客户端角色。首次进行只读试用时，可分配：view-users、query-users、query-groups、view-realm。
3. 复制密钥，位置在客户端的 Credentials 选项卡中。

包含 Admin Console 点击路径、kcadm.sh 命令和本地 Docker Keycloak 的分步说明：docs/getting-started.md。

2. 配置 MCP 客户端

Claude Code 示例（其他客户端：docs/clients.md）：

claude mcp add --transport stdio \
  --env KEYCLOAK_URL=https://keycloak.example.com \
  --env KEYCLOAK_AUTH_REALM=demo \
  --env KEYCLOAK_CLIENT_ID=mcp-admin \
  --env KEYCLOAK_CLIENT_SECRET="$KEYCLOAK_CLIENT_SECRET" \
  keycloak -- npx -y keycloak-model-context-protocol@1

或使用 JSON（Claude Desktop，claude_desktop_config.json）：

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "keycloak-model-context-protocol@1"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_AUTH_REALM": "demo",
        "KEYCLOAK_CLIENT_ID": "mcp-admin",
        "KEYCLOAK_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}

3. 提出你的第一个问题

列出你可以访问的 realm，然后显示 realm demo 中最前面的 10 个用户。

如果你得到了回答，就完成了。如果没有，请参阅 docs/troubleshooting.md。

配置

所有设置均为环境变量。只需设置 KEYCLOAK_URL 和一组凭据。

变量	默认值	用途
KEYCLOAK_URL	（必填）	Keycloak 服务的基础 URL
KEYCLOAK_AUTH_REALM	master	登录账户或客户端所在的 realm
KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET	无	client_credentials 登录（推荐）
KEYCLOAK_USERNAME / KEYCLOAK_PASSWORD	无	密码授权登录（客户端默认为 admin-cli）
KEYCLOAK_GRANT_TYPE	自动	client_credentials 或 password；根据设置的内容自动检测
KEYCLOAK_MCP_TOOLSETS	core,groups,roles	已启用的工具集，或 all
KEYCLOAK_MCP_READ_ONLY	false	仅注册只读工具
KEYCLOAK_MCP_REALMS	全部	以逗号分隔的目标 realm 允许列表
KEYCLOAK_MCP_ALLOW_MASTER_WRITE	false	允许在 master realm 中使用写入工具
KEYCLOAK_MCP_REQUIRE_CONFIRMATION	true	具有破坏性和敏感性的工具需要 confirm: true
KEYCLOAK_MCP_TIMEOUT_MS	30000	Keycloak 请求的 HTTP 超时时间
KEYCLOAK_MCP_LOG_LEVEL	info	debug、info、warn 或 error（stderr）

完整参考文档包含示例、验证规则和工具到角色的对应关系表：docs/configuration.md。

工具集和工具

工具的命名格式为 <domain>_<verb>。除非设置 KEYCLOAK_MCP_TOOLSETS，否则仅启用默认工具集。在只读模式下，仅注册 read 类型的工具。

工具集	默认	工具
core	是	realm_list、realm_get、user_search、user_get、user_create（敏感）、user_update（敏感）、user_delete（破坏性）、user_send_actions_email（敏感）
groups	是	group_list、group_members_list、user_group_add（敏感）、user_group_remove（破坏性）
roles	是	role_list、user_roles_list、user_role_assign（敏感）、user_role_revoke（破坏性）
clients	否	client_list、client_get
sessions	否	user_sessions_list、user_logout（破坏性）
events	否	event_list、admin_event_list
security	否	user_brute_force_status、user_brute_force_unlock（敏感）

每个工具的详细信息（参数、输出、所需角色）：docs/tools-reference.md。

提示词和资源

提示词是基于工具构建的引导式工作流。它们会显示在客户端的提示词选择器中（在 Claude Code 中以斜杠命令的形式显示）。realm 参数支持自动补全。

提示词	功能说明
onboard_employee	创建用户、添加群组和角色，并发送欢迎电子邮件
offboard_employee	审查离职员工的账户、结束会话并停用账户（不会删除账户）
audit_realm_security	以只读方式进行安全审查，并按优先级列出发现的问题
investigate_failed_logins	分析登录失败情况和锁定状态，不做任何更改

资源是只读 JSON 文档，并按相同的 realm 允许列表进行筛选：

URI	内容
keycloak://realms	可访问的 realm 名称
keycloak://realms/{realm}	realm 设置中的安全子集
keycloak://realms/{realm}/security-summary	暴力破解、密码策略、SSL、OTP、事件标记、客户端暴露数量（不含机密信息）
keycloak://realms/{realm}/users/{userId}	单个用户的基本字段（不含属性和凭据）

安全

• 首先遵循最小权限原则。 使用仅限于一个 realm、且只分配所需 realm-management 角色的服务帐户客户端。角色矩阵见 docs/configuration.md。
• 每项更改都需要确认（KEYCLOAK_MCP_REQUIRE_CONFIRMATION=true）：破坏性和敏感工具会先显示预览。授予管理权限（包括通过复合角色和父组授予）、更改具有管理权限的帐户资料、为此类帐户发送操作邮件，以及更改服务自身帐户，都需要确认；设置 KEYCLOAK_MCP_REQUIRE_CONFIRMATION=false 也无法关闭这些确认。系统会拒绝为服务自身帐户授予角色或组、更改其资料或发送操作邮件。
• 防止帐户被接管： 更改后的电子邮件地址会被标记为未经验证，除非另有说明；操作邮件链接的有效期最长为 24 小时；预览会列出收件人地址，并说明目标帐户是否具有管理权限。
• 限制影响范围： KEYCLOAK_MCP_READ_ONLY、KEYCLOAK_MCP_REALMS，以及对 master 的写入保护（默认关闭）。
• 输出和日志中不包含机密信息。 凭据在 stderr 中会被遮蔽；工具绝不会返回客户端机密、用户凭据或属性。
• 提示词注入： 将来自 Keycloak 的名称和描述视为数据。随附的提示词会明确说明这一点；不需要写入工具时，请保持其禁用状态。

威胁模型、加固检查清单以及漏洞报告方式见：docs/security.md 和 SECURITY.md。

示例提示词

• “你能看到哪些 realms？给我看看 realm demo 的设置。”
• “找出 demo 中所有电子邮件地址以 @example.com 结尾且已禁用的用户。”
• “在 demo 中创建用户 jdoe（Jane Doe，[email protected]），将她添加到组 engineering，并向她发送设置密码的电子邮件。”
• “组 ops 中有哪些成员？alice 有哪些角色，包括复合角色？”
• “对 demo 运行 audit_realm_security 提示词。” (完整审计需要 clients 和 events 工具集)
• “昨晚有许多登录失败。调查 realm demo。”
• “将 demo 中的 bob 办理离职：结束他的会话并禁用帐户。”

文档

文档	内容
docs/getting-started.md	本地 Keycloak、服务帐户设置、首次运行、MCP Inspector
docs/configuration.md	环境变量参考、角色矩阵、角色配置、TLS
docs/clients.md	Claude Desktop、Claude Code、VS Code、Cursor、通用客户端
docs/tools-reference.md	每种工具的详细说明
docs/security.md	威胁模型与加固
docs/troubleshooting.md	症状、原因、解决方法
docs/architecture.md	组件、流程、设计决策
CHANGELOG.md	发行说明

从 0.x 升级

1.0 版本更改了默认设置：必须提供凭据（不再回退到 admin/admin），破坏性工具会要求确认，并且工具已重命名为 <domain>_<verb>（例如，create-user 变为 user_create，delete-user 变为 user_delete）。旧变量 KEYCLOAK_ADMIN 和 KEYCLOAK_ADMIN_PASSWORD 仍然可用，但已弃用。请参阅迁移指南。

Contributing and license

Contributions are welcome. See CONTRIBUTING.md and the Code of Conduct. Released under the MIT License.