mcp-keycloak

一个用于 Keycloak 的 Model Context Protocol 服务器。它让支持 MCP 的客户端（如 Claude Desktop、Claude Code 等）能够检查和管理 Keycloak 的 realm、用户、客户端、角色和组——安全性完全由标志（flags）控制。

设计目标是 默认安全：以只读模式启动，将范围限定在允许的 realm 列表（allowlist）内，保护敏感 realm 不受更改，并让破坏性操作必须通过显式的选入（opt-in）才能执行。

特性

• 多 realm — 每个工具都接受一个 realm 参数；作用域可通过允许列表（allowlist）限定。

• 访问模式 — read-only → read-write → admin，进阶级设计，任何模式都不会暴露高于其层级的工具。

• 安全开关 — realm 允许列表、受保护 realm、删除控制（delete gating）、试运行（dry-run）和 JSON 审计日志（见下表）。

• 两种认证策略 — 机密客户端服务账号（推荐）或管理员用户名/密码。

• 零重型依赖 — 一个基于 fetch 的精简 Admin REST 客户端，外加 MCP SDK 和 zod。

Related MCP server: mcp-keycloak-admin

安全模型

这些安全层级相互独立——例如，admin 模式下如果 KEYCLOAK_ALLOW_DELETE=false，就可以创建和更新用户，但不能删除用户。

工具

检查 (read-only+): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups

写入 (read-write+): create_user, update_user, reset_password, logout_user

管理 (admin): delete_user

与你的 MCP 客户端配合使用

支持 Claude Code、Claude Desktop、Cursor、OpenAI Codex CLI、Windsurf、VS Code (Copilot) 以及任何其他 MCP 客户端——每个客户端的配置方式另见 docs/CLIENTS.md。

安装

npm install
npm run build

配置

复制 .env.example 并按需填入内容，或者直接在 MCP 客户端配置中设置这些变量。推荐使用一个带有所需 realm-management 角色的机密客户端作为凭据。

使用 Claude Desktop 运行

在 MCP 客户端配置中添加该服务器（claude_desktop_config.json 或通过 claude mcp add）：

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-keycloak/dist/index.js"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only",
        "KEYCLOAK_REALM_ALLOWLIST": "app,customers"
      }
    }
  }
}

只有当你有意让模型进行变更时，才将 KEYCLOAK_MODE 提升到 read-write（如需删除，还要设置为 admin + KEYCLOAK_ALLOW_DELETE=true）。

开发

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

发布

该服务器附带一个用于官方 MCP 注册表的 server.json，以及一个用于 npm 所有权校验的 mcpName。发布到 npm 并在 MCP registry、Smithery、Glama、Cursor 和 PulseMCP 等平台列出，请参阅 PUBLISHING.md。

许可证

MIT