skycloak-mcp

Skycloak（托管式 Keycloak）的官方 Model Context Protocol 服务器：从任意 MCP 客户端（Claude Desktop、Claude Code、Cursor）管理你的集群、领域、应用和单点登录。

状态： 早期发布版本。工具覆盖范围正在扩展；请参阅变更日志了解当前可用功能。

快速开始

claude mcp add --transport http skycloak https://mcp.skycloak.io

无需 API 密钥、客户端 ID 或配置。你的浏览器会自动打开，登录 Skycloak，工具便会显示。任何支持流式 HTTP 的 MCP 客户端都以相同方式工作：只需提供 URL，无需其他操作。

然后可以提出例如：

• “我的哪些 Keycloak 集群升级滞后了？”

• “在 EU 集群上创建一个支持 Google 和 GitHub 登录的暂存领域。”

• “上周谁被添加到了生产领域？”

• “设置一个 SIEM 目标，将管理事件转发到我们的 Datadog Webhook。”

Related MCP server: MCP Authentik

认证与安全性

• 托管 HTTP + OAuth（无需配置凭据）。 将客户端指向 https://mcp.skycloak.io，不带任何请求头。服务器在 /.well-known/oauth-protected-resource 位置返回 401，并附上指向其 RFC 9728 元数据的指针；客户端针对 Skycloak 登录领域运行浏览器授权码流程，获得的访问令牌被交换为一个短期有效、作用域限定于工作空间的 API 密钥，本次会话将使用该密钥。密钥有效期为一小时，并会自动续期。客户端配置中不会存储任何内容。

• 托管 HTTP + API 密钥。 在 Skycloak 仪表盘 中创建一个密钥，然后以 Authorization: Bearer <key>（或 API-Key: <key>）的形式发送。每个请求自带凭据，且仅作用于该凭据所属的工作空间。服务器不维护会话状态，因此一个请求不会继承另一个调用者的权限。密钥在连接时不会验证：Skycloak API 是权威依据，无效密钥会在首次工具调用时返回 401，而非连接时。

• 工具匹配你的角色。 通过 OAuth 连接时，工具列表会根据会话作用域进行裁剪，因此只读工作空间成员不会看到会返回 403 的写入工具。使用 API 密钥时，整个工具集都会注册，因为密钥的作用域对服务器不可见，未授权的调用会在 API 层面返回 403。

• 本地 stdio。 运行 skycloak-mcp init，在浏览器中批准（OAuth 2.0 设备授权流程）。它会生成一个工作空间作用域的 API 密钥，存储在你的操作系统密钥链中，并自动检测你的默认工作空间（通过 --workspace <id> 可指定其他工作空间）。skycloak-mcp logout 会删除已存储的密钥。

• 无头 / CI 环境。 设置环境变量 SKYCLOAK_API_KEY（在 Skycloak 仪表盘 中创建密钥）可完全跳过浏览器流程。该环境变量始终优先于密钥链。

• 写入操作由你的凭据控制，而非标志位。 https://mcp.skycloak.io 上的托管服务器支持写入能力，你能实际修改的内容受限于密钥的作用域和工作空间角色：只读成员无论工具列表如何，都无法进行任何变更。在 URL 后添加 ?readonly=true 可强制会话使用只读工具面。本地二进制文件则相反，除非使用 --allow-writes 启动，否则不会注册任何写入工具。

• 集群凭据需主动授权。 get_cluster_credentials 会返回集群的 Keycloak 管理员凭据，持有该密钥的助手将能看到这些凭据，因此 init 默认不请求此作用域。使用携带该作用域的密钥：在仪表盘中创建，或通过 stdio 登录时使用 skycloak-mcp init --allow-credentials。若无此作用域，该工具会返回一个 403 错误，并说明两种获取路径。

• 破坏性工具需确认： 例如删除领域，需要显式提供 confirm=true 参数。

• 请求会根据你的 Skycloak 套餐进行速率限制；收到 429 响应时，服务器会返回 Retry-After 头部。

工具

共 129 个工具：58 个只读，71 个写入。只读工具始终可用。在托管服务器上，写入工具也会注册，但受凭据作用域限制；本地二进制文件仅在使用 --allow-writes 启动时注册写入工具。

工具名称带有 skycloak_ 前缀，下表已省略，因此 list_clusters 在客户端中实际为 skycloak_list_clusters。

约定： 破坏性工具（delete_*、uninstall_extension、cancel_cluster_upgrade）需要 confirm=true。create_cluster 是异步的：轮询 get_cluster 直到集群状态变为 available。create_domain 返回客户必须创建的 DNS 记录；verify_domain 触发 DNS 检查。set_theme_assignment 根据 Keycloak 主题类型激活自定义主题（空字符串重置为内置默认主题）。update_cluster_security 不会修改 CAPTCHA 设置。领域导入/导出移动单个领域的配置，与 create_export（导出整个集群数据库）不同：两者都是异步的，且领域归档始终加密，因此导出时使用的密码在重新导入时是必需的。领域可以直接从现有导出（source_export_id）导入，也可以从上传的归档（create_realm_import_upload_url、PUT、然后 upload_s3_key）导入；导入会创建一个新领域，并在名称冲突时拒绝操作而非覆盖，且需要 confirm=true，因为它会同时导入用户和凭据。

连接

对于托管的 HTTP，最简单的路由是 OAuth，它根本不需要凭据：

claude mcp add --transport http skycloak https://mcp.skycloak.io

首次调用会打开您的浏览器，您在 Skycloak 登录页面中批准，然后工具就会出现。如果您属于多个工作区，请指定您想要的那个：

claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"

否则，在 Skycloak 仪表板中创建一个 API 密钥，并配置您的 MCP 客户端将其作为 bearer 令牌发送：

claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"

这会将以下内容添加到 .claude.json：

{
  "mcpServers": {
    "skycloak": {
      "type": "http",
      "url": "https://mcp.skycloak.io",
      "headers": {
        "Authorization": "Bearer sk_sc_XXX"
      }
    }
  }
}

对于本地 stdio，登录一次，然后将您的客户端指向 skycloak-mcp run：

skycloak-mcp init        # one-time browser sign-in; stores a key in your keychain

Claude Desktop / Cursor（本地，stdio）：

{
  "mcpServers": {
    "skycloak": {
      "command": "skycloak-mcp",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Claude Code：

claude mcp add skycloak -- skycloak-mcp run --transport stdio

对于无头/CI 环境（无浏览器），跳过 init 并直接传递密钥：将 "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } 添加到配置中，或使用 claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio。

仅当您打算进行更改时才添加 --allow-writes（使用 skycloak-mcp init --allow-writes 登录，或使用具有写入权限的密钥）。

在托管的 HTTP URL 中添加 ?readonly=true 以仅暴露该 HTTP 会话的只读工具，或添加 ?readonly=false 以请求具有写入能力的工具界面。查询参数默认为 false，但仅当服务器以 --allow-writes 启动时才会注册写入工具。

添加 ?workspace=<uuid> 来选择 OAuth 会话作用于哪个工作区。仅当您属于多个工作区时才需要；如果只有一个工作区，服务器会自动为您选择；如果您属于多个工作区且未指定，则连接会失败，并显示一条消息列出它们。

运行 HTTP 传输

skycloak-mcp run --transport http --http-addr :8080

它不需要自己的凭据：调用者按请求提供自己的凭据，因此无需在部署时注入任何内容。GET /healthz 和 GET /readyz 未经身份验证，仅报告进程已启动；它们故意不探测 Skycloak API，因此上游故障不会同时导致所有副本的探测失败。服务器不保存会话状态，因此副本不需要会话亲和性，可以自由扩展或滚动更新。SIGTERM 会停止新连接并排空正在进行的调用。

只要设置了 SKYCLOAK_ISSUER 和 SKYCLOAK_DASHBOARD_URL（默认情况下已设置），OAuth 路径就会启用。此时 GET /.well-known/oauth-protected-resource 会以未经身份验证的方式提供，将领域命名为授权服务器。其 resource 值在设置 SKYCLOAK_PUBLIC_URL 时取自该变量，否则取自请求自身的 Host 和 scheme，因此位于入口后面的单主机部署无需额外配置。Scheme 来自 X-Forwarded-Proto（如果存在），否则对于非回环主机默认为 https，因为 TLS 在上游终止，发布 http:// 标识符不会匹配客户端连接的 URL。如果您的入口重写了 Host，请设置 SKYCLOAK_PUBLIC_URL。该文档还列出 openid profile email 作为其 scopes_supported，并且 WWW-Authenticate 质询将其作为 scope 参数重复，因此读取任一参数的客户端会向领域请求这些参数：openid 是必需的，因为令牌交换使仪表板调用 Keycloak 的用户信息端点，而 Keycloak 会拒绝没有该作用域的令牌。如果令牌到达时没有该作用域，验证时会返回 401 和质询，而不是将其带到无法成功的交换中，因此仍然持有旧授权令牌的客户端会停止重试并重新登录。清空发行者或仪表板变量中的任何一个都会完全关闭 OAuth，服务器将恢复为仅质询 API 密钥，不再有其他操作。

启动时会记录一行，显示已解析的配置（oauth=、issuer=、dashboard=、public_url=、endpoint=、allow_writes=），因此无需重新部署即可发现配置错误的部署。每次请求在 OAuth 路径上被拒绝时，都会记录一行，说明失败的阶段（verify、exchange 或 scopes）、调用者收到的状态以及底层错误。验证失败会添加拒绝令牌的检查（expired、wrong_issuer、bad_signature、unknown_key_id、wrong_token_type、no_openid_scope 等）；交换失败会添加仪表板的状态和调用的主机。调用者在令牌验证后显示为令牌的主体，而绝不会作为凭据显示：访问令牌、Authorization 标头以及生成的 API 密钥永远不会被记录。

配置

命令：init（浏览器登录）、run（提供服务）、logout（删除存储的密钥）。init 接受 --workspace <id>、--allow-writes、--allow-credentials 和 --ttl-days（默认为 90）。

开发

make build      # build the server binary
make test       # unit tests
make run        # run on stdio for local testing
make inspector  # MCP Inspector against the local binary
make lint       # golangci-lint
make generate   # regenerate the API client from the OpenAPI spec

internal/apiclient 下的 API 客户端是从 Skycloak OpenAPI 规范使用 oapi-codegen 生成的。

与 API 保持同步

internal/apiclient 中的客户端是从 internal/apiclient/openapi.yaml 使用 oapi-codegen 生成的；运行 make generate 来刷新它。如果提交的生成代码与规范偏离，CI 会失败。请求会在 429/5xx 时重试，并带有 Retry-After 感知的退避。

分发

在每个标签上以 GitHub 二进制文件和 ghcr.io/sky-cloak/skycloak-mcp 容器镜像形式发布，并发布到 MCP Registry 作为 io.skycloak/skycloak-mcp。大多数人两者都不需要：托管的服务器无需安装。

安全

请私下报告漏洞。参见 SECURITY.md。

贡献者

由 Skycloak 的 Guilliano Molaire、Neville Omangi 和 Aphilas 构建。仓库历史在开源时被压缩，因此提交日志不反映谁的贡献。

许可证

Apache-2.0。internal/apiclient/openapi.yaml 中的 OpenAPI 描述是从 Skycloak 平台 API 生成的，版权归 Skycloak 所有；此处包含它以便生成和验证客户端。参见 NOTICE。