Keycloak Admin

mcp-keycloak-admin

一个通过 Keycloak Admin REST API 管理 Model Context Protocol（MCP）服务的实例。默认安全、可配置，并采用简洁的测试驱动架构构建。

兼容 Keycloak 26.x（已针对 26.0.5 验证）。

安装

无需安装 — 直接通过 npm 使用 npx 运行：

npx -y mcp-keycloak-admin

该服务通过 stdio 使用 MCP 通信，因此通常会将其接入 MCP 客户端，而不是手动运行 — 请参阅与 MCP 客户端搭配使用。 刚接触它？快速入门可在几分钟内启动本地 Keycloak 并配置客户端。

为什么使用它

通过 MCP 客户端（助手、IDE、自定义 Agent）管理 Keycloak，意味着将日常操作 — 搜索用户、管理角色、读取事件 — 作为 MCP 工具开放，而无需提供原始管理控制台。该服务通过严格的防护措施实现这一点，确保破坏性操作绝不会静默执行。

功能

• 两种身份验证模式，可通过配置选择：
  • service_account — 使用服务账户的机密客户端 （推荐；无需存储管理员密码）。
  • password — 使用带有管理员用户名和密码的 admin-cli 客户端。
• 默认安全：
  • READ_ONLY 模式会隐藏所有写入和破坏性工具。
  • ALLOWED_REALMS 限制服务可操作的领域。
  • 破坏性操作需要明确确认（使用原生 MCP 征询；对于不支持征询的客户端，则回退到 confirm: true 参数）。
• 整洁架构：不依赖框架的领域层、应用用例和基础设施适配器。不使用原始字符串或数字表示任何业务概念 — 每个概念都是经过验证的值对象。

要求

• Node.js >= 20
• 可访问的 Keycloak 26.x 服务

与 MCP 客户端搭配使用

将服务添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "keycloak-admin": {
      "command": "npx",
      "args": ["-y", "mcp-keycloak-admin"],
      "env": {
        "KEYCLOAK_BASE_URL": "http://localhost:8080",
        "KEYCLOAK_REALM": "demo-realm",
        "AUTH_MODE": "service_account",
        "KC_CLIENT_ID": "mcp-admin",
        "KC_CLIENT_SECRET": "your-secret"
      }
    }
  }
}

请参阅 docs/setup-keycloak.md，了解如何创建 mcp-admin 客户端并为其授予所需的最小权限角色。

多个 Keycloak 实例

每个服务条目对应一个 Keycloak（一个基础 URL + 领域 + 身份验证方式）。如需管理多个环境，请为每个实例添加一个条目 — 每个条目完全隔离，并拥有自己的凭据和防护措施：

{
  "mcpServers": {
    "kc-preprod": {
      "command": "npx",
      "args": ["-y", "mcp-keycloak-admin"],
      "env": {
        "KEYCLOAK_BASE_URL": "https://preprod.example.com",
        "KEYCLOAK_REALM": "preprod-realm",
        "AUTH_MODE": "service_account",
        "KC_CLIENT_ID": "mcp-admin",
        "KC_CLIENT_SECRET": "…",
        "ALLOWED_REALMS": "preprod-realm"
      }
    },
    "kc-prod": {
      "command": "npx",
      "args": ["-y", "mcp-keycloak-admin"],
      "env": {
        "KEYCLOAK_BASE_URL": "https://auth.example.com",
        "KEYCLOAK_REALM": "prod-realm",
        "AUTH_MODE": "service_account",
        "KC_CLIENT_ID": "mcp-admin",
        "KC_CLIENT_SECRET": "…",
        "READ_ONLY": "true",
        "ALLOWED_REALMS": "prod-realm"
      }
    }
  }
}

客户端会按服务为工具命名空间化（例如 kc-prod:keycloak_user_delete），因此不会有在错误环境中执行操作的风险。这是推荐的模式：例如，可以让生产环境保持 READ_ONLY，同时让预生产环境仍可写入。

配置

变量	必填	描述
KEYCLOAK_BASE_URL	是	Keycloak 服务的基础 URL（末尾不带斜杠）。
KEYCLOAK_REALM	是	服务运行所在的 Realm。
AUTH_MODE	是	service_account 或 password。
KC_CLIENT_ID	如果使用 service_account	机密客户端 ID（例如 mcp-admin）。
KC_CLIENT_SECRET	如果使用 service_account	客户端密钥。
KC_ADMIN_USERNAME	如果使用 password	管理员用户名。
KC_ADMIN_PASSWORD	如果使用 password	管理员密码。
KC_ADMIN_REALM	否（默认为 master）	存放管理员用户的 Realm（password 模式）。
READ_ONLY	否（默认为 false）	为 true 时，不会注册写入/破坏性工具。
ALLOWED_REALMS	否	以逗号分隔的 Realm 允许列表。留空 = 全部。

完整示例见 .env.example。

工具

级别：[R] 只读 · [W] 写入 · [D] 破坏性（需要确认）。每个工具都带有相应的 MCP 注解 （readOnlyHint / destructiveHint / idempotentHint）。

当前已实现：

注意： 此表对应 main 分支，该分支可能领先于上方版本徽章显示的最新 npm 版本。要确认当前安装中有哪些内容，请检查 npm view mcp-keycloak-admin version，并固定到 mcp-keycloak-admin@latest。 | 工具 | 级别 | 描述 | | ------------------------------------------- | ----- | ------------------------------------------------------------------- | | keycloak_user_search | R | 按电子邮件、用户名或自由文本搜索 Realm 用户。 | | keycloak_user_get | R | 按 ID 获取单个用户。 | | keycloak_user_sessions_list | R | 列出用户的活动会话。 | | keycloak_user_create | W | 创建 Realm 用户。 | | keycloak_user_update | W | 更新用户的电子邮件、姓名或启用标志。 | | keycloak_user_set_enabled | W | 启用或禁用用户。 | | keycloak_user_send_action_email | W | 发送必需操作电子邮件。 | | keycloak_user_reset_password | D | 为用户设置新密码。 | | keycloak_user_logout | D | 撤销用户的所有会话。 | | keycloak_user_delete | D | 永久删除用户（ID 和用户名必须匹配）。 | | keycloak_role_list | R | 列出 Realm 角色。 | | keycloak_user_roles_get | R | 列出用户的 Realm 角色。 | | keycloak_user_role_assign | W | 向用户授予 Realm 角色。 | | keycloak_user_role_unassign | D | 撤销用户的 Realm 角色。 | | keycloak_client_roles_list | R | 列出客户端定义的角色。 | | keycloak_user_client_roles_get | R | 列出用户的客户端角色。 | | keycloak_user_client_role_assign | W | 向用户授予客户端角色。 | | keycloak_user_client_role_unassign | D | 撤销用户的客户端角色。 | | keycloak_client_list | R | 列出 Realm 客户端。 | | keycloak_client_create | W | 创建 Realm 客户端。 | | keycloak_client_update | W | 更新客户端（启用状态、公开状态、重定向 URI、CORS Web 源）。 | | keycloak_client_delete | D | 删除客户端。 | | keycloak_client_get | R | 按 clientId 获取客户端。 | | keycloak_client_get_secret | R | 读取客户端密钥（除非使用 reveal，否则会隐藏）。 | | keycloak_client_scopes_list | R | 列出 Realm 的客户端作用域。 | | keycloak_client_default_scopes_get | R | 列出客户端的默认作用域。 | | keycloak_client_mappers_list | R | 列出客户端的协议映射器。 | | keycloak_client_scope_assign | W | 为客户端添加默认作用域。 | | keycloak_client_scope_unassign | D | 从客户端移除默认作用域。 | | keycloak_client_regenerate_secret | D | 重新生成客户端密钥（旧密钥将失效）。 | | keycloak_group_list | R | 列出 Realm 的顶级组。 | | keycloak_group_members_list | R | 列出组成员。 | | keycloak_user_groups_list | R | 列出用户所属的组。 | | keycloak_group_create | W | 创建顶级组。 | | keycloak_group_member_add | W | 将用户添加到组。 | | keycloak_group_role_assign | W | 向组授予 Realm 角色。 | | keycloak_group_member_remove | D | 从组中移除用户。 | | keycloak_group_delete | D | 删除组。 | | keycloak_idp_list | R | 列出身份提供商。 | | keycloak_idp_get | R | 按别名获取身份提供商。 | | keycloak_idp_mappers_list | R | 列出身份提供商的映射器。 | | keycloak_idp_create | W | 创建身份提供商。 | | keycloak_idp_delete | D | 删除身份提供商。 | | keycloak_federation_list | R | 列出用户联合（LDAP/Kerberos）提供商。 | | keycloak_federation_get | R | 按 ID 获取联合提供商。 | | keycloak_federation_sync | W | 触发用户同步（全部或仅同步变更项）。 | | keycloak_auth_flows_list | R | 列出身份验证流程。 | | keycloak_auth_required_actions_list | R | 列出必需操作。 | | keycloak_auth_required_action_set_enabled | W | 启用或禁用必需操作。 | | keycloak_authz_resources_list | R | 列出客户端的授权资源。 | | keycloak_authz_policies_list | R | 列出客户端的授权策略。 | | keycloak_authz_permissions_list | R | 列出客户端的授权权限。 | | keycloak_events_login | R | 读取近期登录事件（可筛选）。 | | keycloak_events_admin | R | 读取近期管理事件。 | | keycloak_realm_get_config | R | 读取关键 Realm 配置标志。 | | keycloak_server_info | R | 读取 Keycloak 服务版本。 | 有关参数和示例，请参阅 docs/users.md、docs/roles.md、 docs/clients.md、docs/groups.md 和 docs/events-realm.md；有关安全模型，请参阅 docs/security.md。

路线图

该架构旨在通过精简的用例和工具持续扩展。剩余候选项：授权策略／权限的增删改查与评估、身份验证流程变更（复制／添加执行项），以及高级联邦和身份提供商配置。有关如何添加用例，请参阅 docs/development.md。

开发

npm install
npm test              # unit tests
npm run test:integration  # spins up a real Keycloak 26 via Testcontainers (needs Docker)
npm run check         # typecheck + lint + format check + unit tests
npm run build         # bundle to dist/

发布流程已自动化——请参阅 docs/releasing.md。

贡献

欢迎贡献——请阅读 CONTRIBUTING.md。

许可证

MIT