mcp-keycloak

mcp-keycloak

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

设计目标是默认安全：以只读模式启动，将范围限定在允许列表中的 realm，保护敏感 realm 免遭修改，并通过明确选择加入来控制破坏性操作。

功能

• 多 realm — 每个工具都接受 realm 参数；可使用允许列表限定范围。
• 访问模式 — read-only → read-write → admin，分层设置，确保任何模式都不会暴露高于其级别的工具。
• 安全标志 — realm 允许列表、受保护的 realm、删除控制、试运行和 JSON 审计日志（见下文）。
• 两种身份验证策略 — 机密客户端服务账号（推荐）或管理员用户名/密码。
• 无沉重依赖 — 轻量、基于 fetch 的 Admin REST 客户端，以及 MCP SDK 和 zod。

安全模型

关注点	标志	默认值	效果
服务可以执行哪些操作？	KEYCLOAK_MODE	read-only	read-only 仅开放读取工具；read-write 增加修改操作；admin 增加破坏性工具。高于当前模式的工具永远不会注册。
哪些 realm 在作用范围内？	KEYCLOAK_REALM_ALLOWLIST	(全部)	以逗号分隔。设置后，任何对列表外 realm 的操作都会被拒绝。
哪些 realm 永远只读？	KEYCLOAK_PROTECTED_REALMS	master	受保护的 realm 可以读取，但无论模式如何，都不能修改或删除。
是否可以删除？	KEYCLOAK_ALLOW_DELETE	false	delete_* 工具必须同时满足此条件和 admin 模式。
预览操作但不触及 Keycloak	KEYCLOAK_DRY_RUN	false	写入/admin 工具会验证并记录操作意图，然后直接返回，不会调用 Keycloak。
审计追踪	KEYCLOAK_AUDIT_LOG	true	每次受控操作都会向 stderr 输出一行 JSON（ALLOW / DENY / DRY_RUN）。
交互式确认	(自动)	—	执行前，破坏性和高影响操作会通过 MCP elicitation 提示用户批准；不支持 elicitation 的客户端会退回到 *_ALLOW_* 控制项。

这些层级彼此独立——例如，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

快速开始 — 添加到你的 Agent

已发布到 npm，包名为 @dockndevai/mcp-keycloak。无需克隆或构建——MCP 客户端会在需要时通过 npx 运行它。请从 read-only 模式开始；所有变量见 .env.example，各客户端的完整指南见 docs/CLIENTS.md。

Claude Code（CLI）

claude mcp add keycloak -e KEYCLOAK_URL="https://keycloak.example.com" -e KEYCLOAK_CLIENT_ID="admin-cli" -e KEYCLOAK_CLIENT_SECRET="your-secret" -e KEYCLOAK_MODE="read-only" -- npx -y @dockndevai/mcp-keycloak

Claude Desktop · Cursor · Windsurf — 在 claude_desktop_config.json、.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json 中使用相同配置块：

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-keycloak"
      ],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — 在 ~/.codex/config.toml 中：

[mcp_servers.keycloak]
command = "npx"
args = ["-y", "@dockndevai/mcp-keycloak"]
env = { KEYCLOAK_URL = "https://keycloak.example.com", KEYCLOAK_CLIENT_ID = "admin-cli", KEYCLOAK_CLIENT_SECRET = "your-secret", KEYCLOAK_MODE = "read-only" }

VS Code（GitHub Copilot，Agent 模式） — 在 .vscode/mcp.json 中：

{
  "servers": {
    "keycloak": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-keycloak"
      ],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only"
      }
    }
  }
}

配置

复制 .env.example 并填写，或直接在 MCP 客户端配置中设置变量。建议使用具有所需 realm-management 角色的机密客户端凭据。

从源代码运行（开发）

建议使用上方发布的包。从克隆的仓库运行：

npm install
npm run build
node dist/index.js   # with the environment variables set

开发

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

发布

此服务提供 server.json，用于官方 MCP 注册表，以及 mcpName，用于验证 npm 所有权。有关发布到 npm 并在 MCP 注册表、Smithery、Glama、Cursor 和 PulseMCP 上列出，请参阅 PUBLISHING.md。

许可证

MIT