内容
# mcp-keycloak-admin
[](https://www.npmjs.com/package/mcp-keycloak-admin)
[](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/ci.yml)
[](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/codeql.yml)
[](LICENSE)
一个 [模型上下文协议](https://modelcontextprotocol.io) （MCP）服务器，通过其管理REST API管理 [Keycloak](https://www.keycloak.org) 实例。默认安全，可配置，并采用干净的测试驱动架构。
兼容 **Keycloak 26.x** （验证 against 26.0.5）。
## 安装
无需安装 - 直接从npm运行，使用 `npx`:
```bash
npx -y mcp-keycloak-admin
```
服务器通过stdio使用MCP，因此通常将其连接到MCP客户端，而不是手动运行 - 请参阅 [与MCP客户端一起使用](#usage-with-an-mcp-client)。新用户？ [快速入门](docs/quickstart.md) 在几分钟内启动本地Keycloak和客户端配置。
## 为什么
从MCP客户端（助手，IDE，自定义代理）管理Keycloak意味着将日常操作（搜索用户，管理角色，读取事件）作为MCP工具公开，而无需提供原始管理控制台。该服务器使用强大的防护措施实现这一点，以确保不会在无声的情况下发生破坏性操作。
## 功能
- **两种身份验证模式**，可通过配置选择：
- `service_account` - 具有服务帐户的机密客户端（推荐；无需存储管理员密码）。
- `password` - 具有管理员用户名/密码的`admin-cli`客户端。
- **默认安全**：
- `READ_ONLY` 模式隐藏每个写入/破坏性工具。
- `ALLOWED_REALMS` 限制服务器可以操作的领域。
- 破坏性操作需要明确确认（本地MCP询问，具有`confirm: true`参数后备客户端不支持询问）。
- **干净的架构**：无框架的领域，应用程序用例和基础设施适配器。没有业务概念作为原始字符串或数字旅行 - 每个都是验证的值对象。
## 要求
- Node.js >= 20
- 可访问的Keycloak 26.x服务器
## 与MCP客户端一起使用
将服务器添加到MCP客户端配置中：
```json
{
"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](docs/setup-keycloak.md) 以创建 `mcp-admin` 客户端并授予其所需的最小权限角色。
### 多个Keycloak实例
每个服务器条目针对 **一个** Keycloak（一个基本URL + 领域 + 身份验证）。要管理多个环境，请为每个实例添加 **一个条目** - 每个实例都完全隔离，具有自己的凭证和防护措施：
```json
{
"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`，而preprod保持可写入。
## 配置
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `KEYCLOAK_BASE_URL` | 是 | Keycloak服务器的基本URL（无尾部斜杠）。 |
| `KEYCLOAK_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`） | 持有管理员用户的领域（`password` 模式）。 |
| `READ_ONLY` | 否（默认 `false`） | 当 `true` 时，不注册写入/破坏性工具。 |
| `ALLOWED_REALMS` | 否 | 允许的领域列表。空 = 所有。 |
完整示例位于 [`.env.example`](.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 | 按电子邮件，用户名或自由文本搜索领域用户。 |
| `keycloak_user_get` | R | 按ID获取单个用户。 |
| `keycloak_user_sessions_list` | R | 列出用户的活动会话。 |
| `keycloak_user_create` | W | 创建领域用户。 |
| `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 | 列出领域角色。 |
| `keycloak_user_roles_get` | R | 列出用户的领域角色。 |
| `keycloak_user_role_assign` | W | 向用户授予领域角色。 |
| `keycloak_user_role_unassign` | D | 从用户中吊销领域角色。 |
| `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 | 列出领域客户端。 |
| `keycloak_client_create` | W | 创建领域客户端。 |
| `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 | 列出领域的客户端范围。 |
| `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 | 列出领域的顶级组。 |
| `keycloak_group_members_list` | R | 列出组的成员。 |
| `keycloak_user_groups_list` | R | 列出用户所属的组。 |
| `keycloak_group_create` | W | 创建顶级组。 |
| `keycloak_group_member_add` | W | 将用户添加到组。 |
| `keycloak_group_role_assign` | W | 向组授予领域角色。 |
| `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 | 读取关键领域配置标志。 |
| `keycloak_server_info` | R | 读取Keycloak服务器版本。 |
参见 [docs/users.md](docs/users.md)， [docs/roles.md](docs/roles.md)， [docs/clients.md](docs/clients.md)， [docs/groups.md](docs/groups.md)和 [docs/events-realm.md](docs/events-realm.md) 以获取参数和示例，并参见 [docs/security.md](docs/security.md) 以获取安全模型。
## 路线图
架构旨在不断增长为薄用例 + 工具。剩余候选人：授权策略/权限CRUD和评估，身份验证流程突变（复制/添加执行），以及高级联合身份提供者配置。参见 [docs/development.md](docs/development.md) 了解如何添加一个。
## 开发
```bash
npm install
npm test # 单元测试
npm run test:integration # 启动一个真实的Keycloak 26 via Testcontainers（需要Docker）
npm run check # 类型检查 + lint + 格式检查 + 单元测试
npm run build # 捆绑到dist/
```
发布是自动的 - 参见 [docs/releasing.md](docs/releasing.md)。
## 贡献
欢迎贡献 - 请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)
