Skycloak

官方

用于Skycloak托管Keycloak的模型上下文协议服务器。可从任何MCP客户端管理集群、领域、应用程序、SSO和用户。

你可以用 Skycloak MCP 做什么?

  • 集群清单与升级 — 列出集群、检查版本,并获取任何落后集群的升级路径。
  • Realm 和应用管理 — 创建或更新 Realm 和应用、分配角色,以及轮换应用客户端密钥。
  • 身份提供商设置 — 向 Realm 添加 OIDC 身份提供商、测试连接,并列出现有的 SSO 连接。
  • 用户和组管理 — 列出 Realm 用户、角色和组,然后分配角色或将用户添加到组。
  • 审计与事件审查 — 查询事件和安全日志,或提取 Realm 最近的登录失败记录并按源 IP 分组。
  • SIEM 和 Webhook 目标 — 创建 SIEM 目标或 Webhook 订阅,并发送测试事件以确认送达。

文档

skycloak-mcp

Smithery

面向 Skycloak(托管式 Keycloak)的官方 Model Context Protocol 服务器:可通过任意 MCP 客户端(Claude Desktop、Claude Code、Cursor)管理集群、realm、应用和 SSO。

**状态:**早期版本。工具覆盖范围正在扩大;请参阅变更日志了解当前可用功能。

快速开始

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

无需 API 密钥、客户端 ID 或配置。浏览器会打开,你登录 Skycloak 后,工具便会显示出来。任何支持可流式 HTTP 的 MCP 客户端都可以用同样的方式工作:只需提供 URL,无需其他设置。

然后试着提出请求:

  • “我的哪些 Keycloak 集群需要升级?”
  • “在 EU 集群上创建一个启用 Google 和 GitHub 登录的 staging realm。”
  • “过去一周有哪些用户被添加到 production realm?”
  • “设置一个 SIEM 目标,将管理员事件转发到我们的 Datadog webhook。”

身份验证与安全

  • **托管 HTTP,使用 OAuth(无需配置凭据)。**将客户端指向 https://mcp.skycloak.io,无需添加请求头。服务器会通过 401 响应,并提供其 RFC 9728 元数据的指针 /.well-known/oauth-protected-resource;客户端随后会针对 Skycloak 登录 realm 执行浏览器授权码流程,并将获得的访问令牌交换为短期、限定工作区范围的 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 默认启用写入能力;你实际可以更改的内容受密钥作用域和工作区角色限制:只读成员无法执行任何修改,无论工具列表显示什么。将 ?readonly=true 添加到 URL,可强制会话仅使用只读工具。本地二进制则相反:除非使用 --allow-writes 启动,否则不会注册写入工具。
  • 集群凭据需主动选择启用。get_cluster_credentials 会返回集群的 Keycloak 管理员凭据,持有密钥的助手随后便能看到这些凭据,因此 init 默认不会请求该作用域。请使用包含该作用域的密钥:可在控制面板中创建,或通过 stdio 使用 skycloak-mcp init --allow-credentials 登录。若没有该作用域,工具会返回 403,并说明这两种获取方式。
  • **破坏性工具需要确认:**例如,删除 realm 时必须显式传入 confirm=true 参数。
  • 请求速率限制取决于你的 Skycloak 方案;收到 429 响应时,服务器会返回 Retry-After。

工具

共有 141 个工具:62 个只读工具和 79 个写入工具。只读工具始终可用。在托管服务器上,写入工具也会注册,但受凭据作用域限制;本地二进制只有在使用 --allow-writes 启动时才会注册这些工具。

工具名称带有 skycloak_ 前缀,下表中省略了该前缀,因此客户端中的 list_clusters 对应 skycloak_list_clusters。

类别只读写入(--allow-writes)
集群list_clusters, get_cluster, list_cluster_locations, list_cluster_types, list_cluster_features, list_cluster_versions, list_cluster_upgrades, get_cluster_upgrade_path, get_cluster_credentials, get_cluster_insights, get_cluster_maintenance_windowcreate_cluster, update_cluster, delete_cluster, cancel_cluster_upgrade, restart_cluster_instances, set_cluster_maintenance_window, delete_cluster_maintenance_window
边缘安全get_cluster_security, list_cluster_captcha_domainsupdate_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realmslist_realms, get_realmcreate_realm, update_realm, delete_realm
应用list_applications, get_application, list_application_roles, list_application_sessionscreate_application, update_application, delete_application, assign_application_role, remove_application_role, rotate_application_secret
身份提供商list_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidccreate_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider
用户、角色与组list_realm_users, get_realm_user, list_realm_roles, get_realm_role, list_realm_groups, get_realm_group, list_realm_group_members, list_user_roles, list_user_groupscreate_realm_user, update_realm_user, delete_realm_user, create_realm_role, update_realm_role, delete_realm_role, create_realm_group, update_realm_group, delete_realm_group, assign_realm_user_role, remove_realm_user_role, add_realm_user_to_group, remove_realm_user_from_group
自定义域名list_domains, get_domain, list_domain_routes, get_domain_routecreate_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route
品牌与主题list_themes, get_theme, get_theme_assignment, get_client_theme_assignment, get_login_branding, get_email_branding, download_theme_content, get_theme_settingsset_theme_assignment, set_client_theme_assignment, update_theme, update_theme_content, update_theme_settings, delete_theme, upsert_login_branding, delete_login_branding, upsert_email_branding, delete_email_branding
扩展list_extensions, list_cluster_extensionsinstall_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTPget_smtpupsert_smtp, delete_smtp, test_smtp
导出与日志list_exports, get_export, get_logs, get_security_logs, query_eventscreate_export, delete_export, export_cluster_events
Realm 导入与导出get_realm_export, get_realm_importcreate_realm_export, create_realm_import, create_realm_import_upload_url
SIEMlist_siem_destinations, get_siem_destinationcreate_siem_destination, update_siem_destination, delete_siem_destination, test_siem_destination
Webhooklist_webhook_event_types, list_webhook_subscriptions, get_webhook_subscriptioncreate_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription
OpenFGAlist_openfga_instances, get_openfga_instancecreate_openfga_instance, delete_openfga_instance

**约定:**破坏性工具(delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances)需要 confirm=true。update_theme_settings 可为工作区启用或停用 exact_theme_names;调用者的 API 密钥必须由工作区所有者或管理员生成,否则即使使用 themes:write,也会收到 403。启用后,现有主题会在后台迁移到其实际提供服务时使用的名称;如果某个主题的内容已被替换为同名内容,在 restart_cluster_instances 滚动重启该集群的 Keycloak 实例之前,get_theme/list_themes/update_theme_content 会报告 restart_required: true。重启可能会延迟到集群维护窗口,而非立即执行;此时会报告 deferred: true,并在已知时提供 next_window。create_cluster 是异步操作:轮询 get_cluster,直到集群处于 available 状态。create_domain 会返回客户必须创建的 DNS 记录;verify_domain 会触发 DNS 检查。set_theme_assignment 会按 Keycloak 主题类型激活自定义主题(空字符串会重置为内置默认值)。update_theme_content 会原位替换主题归档(base64 ZIP 或 content_base64 中的 Keycloakify JAR),同时保留主题 ID、名称、realm 和应用分配,因此编辑主题不再需要先删除再重新上传。由于被覆盖的归档无法恢复,此操作需要 confirm=true;而 update_theme 仍只会更改名称、描述和版本。有关如何调用该工具,请参阅 docs/theme-content-update.md。update_cluster_security 不会更改 CAPTCHA 设置。Realm 导入/导出用于迁移单个 realm 的配置,与 create_export 不同;后者会转储整个集群的数据库。两者都是异步操作,且 realm 归档始终经过加密,因此再次导入时需要提供导出时使用的密码。可以直接从现有导出文件导入 realm(source_export_id),也可以从上传的归档导入(create_realm_import_upload_url,PUT,然后调用 upload_s3_key);导入会创建一个 realm,如果名称冲突则拒绝操作而不会覆盖现有 realm。由于导入内容包含用户和凭据,因此需要 confirm=true。

**OpenFGA 实例:**每个 OpenFGA 工具都需要 cluster_id。create_openfga_instance 会将 OpenFGA 实例绑定到集群中的一个 realm;每个 realm 最多只能绑定一个实例。如果工作区方案不包含 OpenFGA,或工作区已达到实例数量上限,则会返回 403;如果该 realm 已有实例,则返回 409;如果该 realm master、不存在或已停用,则返回 422。此操作是异步的:轮询 get_openfga_instance,直到 status 变为 ready 或 failed。该实例只接受来自该 realm 且包含其受众的令牌;get_openfga_instance 会返回调用该实例所需的 api_url、issuer 和 audience。用于将受众写入 realm 令牌的受众映射器会添加到 Keycloak 中。无需 OpenFGA 访问权限即可列出和删除实例。delete_openfga_instance 会移除部署、路由和数据库,其中的授权数据无法恢复;实例在删除完成前会显示为 deleting。

集群位置:location 在 create_cluster 中,以及在 list_clusters、get_cluster 和 list_cluster_locations 的返回值中,均为以下值之一(不区分大小写):us(美国东部)、us-west(美国西部)、ca(加拿大)、eu(欧洲)或 au(澳大利亚)。us 始终表示美国东部。只有获准访问 us-west 的工作区才能使用该位置:list_cluster_locations 会列出所有 available 对你的工作区设为 true 的位置;如果在你无权使用的位置创建集群,API 会返回 400 "location not available"。

提示

八个提示可帮助你开始使用这些工具。客户端会将它们显示为斜杠命令或建议操作;每个提示都接受参数(realm、集群、时间范围),并引导模型按正确顺序调用合适的工具。

提示词功能
audit_self_registration查找一个或所有集群中仍允许自行注册的所有 realm
review_upgrades找出 Keycloak 版本落后的集群,并规划升级路径
triage_failed_logins获取某个 realm 最近的登录失败记录,并按来源 IP 分组
review_identity_providers列出某个 realm 的 SSO 连接,并检查指定连接是否已启用
review_admin_changes显示某个 realm 最近的变更记录,重点关注登录和安全设置
provision_environment创建集群、添加 realm 并配置身份提供方,逐步确认每项操作
set_up_custom_domain添加自定义域名,返回准确的 DNS 记录,完成验证并将其路由到某个 realm
rotate_client_secret重新生成应用的客户端密钥,并在操作前明确说明影响范围

提示词的访问控制方式与其提及的工具相同:三个会修改数据的提示词仅提供给能够调用其引用的写入工具的会话,并且其中的指令会要求模型在进行任何更改前先向你确认。破坏性工具仍受 confirm=true 要求约束。

技能

提示词是一个起点,而技能则是模型按需加载的完整操作手册。服务器提供四项技能,通过草案版 SEP-2640 Skills 扩展提供:它在 capabilities 中声明 io.modelcontextprotocol/skills,响应 skills/list 和 skills/get,并将每个 SKILL.md 作为普通资源提供于 skill://<name>/SKILL.md,其列表条目中包含 sha256 摘要。OpenAI 的插件目录会按完全相同的格式导入技能。

技能内容
auth-incident-triage排查“用户无法登录”:利用事件、WAF 日志和集群健康状况,区分平台故障、攻击和配置变更。只读
enterprise-sso-rollout端到端地将企业 IdP 接入 realm:验证 issuer、注册上游应用、配置 broker、测试连接,并根据真实登录事件进行验证
keycloak-migration-doctor在执行 Keycloak 导出、导入或迁移前,检查支持团队实际遇到的阻碍(脚本策略、旧版 /auth 路径、部分导出的预期),并通过读取实际的 error_message 诊断失败的作业,而不是依赖通用的仪表板通知
keycloak-upgrade-readiness评估版本差异,确定新版 Keycloak 会破坏哪些内容(扩展、主题),并以导出作为回滚方案,安排跨环境的发布顺序

技能的访问控制方式与其提及的工具相同:围绕写入工具构建的三项工作流不会提供给只读会话;限定范围的会话也只会获得其实际拥有相应工具的技能。源文件位于 internal/tools/skills/,每项技能各占一个目录,采用标准的 Agent Skills 格式,因此也可以直接复制到本地技能目录中使用。

连接

对于托管 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 token 发送该密钥:

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"
      }
    }
  }
}

Gemini CLI 会从此仓库中的清单安装托管服务器作为扩展:

gemini extensions install https://github.com/sky-cloak/skycloak-mcp

Antigravity 会从 plugins/skycloak/ 中的 bundle 安装托管服务器作为插件:

agy plugin install ./plugins/skycloak

Copilot CLI 会从仓库根目录下的 Agent Plugins 清单安装;需先批准该条目:

copilot plugin install skycloak@awesome-copilot

对于本地 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 登录,或使用具有写入权限范围的密钥)。

将 ?readonly=true 添加到托管 HTTP URL,可让该 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 会在无需身份验证的情况下提供,并将 realm 指定为授权服务器。其 resource 值在设置时取自 SKYCLOAK_PUBLIC_URL,否则根据请求自身的 Host 和 scheme 推导,因此单主机部署在 ingress 后面时无需额外配置。若存在 X-Forwarded-Proto,则使用其中的 scheme;否则,对于非 loopback 主机,默认使用 https,因为 TLS 在上游终止,发布 http:// 标识符将与客户端连接时使用的 URL 不匹配。如果你的 ingress 会重写 Host,请设置 SKYCLOAK_PUBLIC_URL。该文档还会将 openid profile email 列为其 scopes_supported,而 WWW-Authenticate 挑战也会将它们作为 scope 参数重复列出,因此读取其中任一项的客户端都会向 realm 请求这些内容:必须包含 openid,因为令牌交换会让仪表板调用 Keycloak 的 userinfo 端点,而 Keycloak 会拒绝未获授此项的令牌。若令牌到达时缺少此项,验证阶段会以 401 和挑战信息拒绝该令牌,而不会将其带入注定失败的交换流程;因此,仍持有先前授权的客户端会停止重试并重新登录。将 issuer 或 dashboard 变量中的任意一个清空都会完全关闭 OAuth,服务器将恢复为仅通过 API 密钥发起质询。

OPENAI_APPS_CHALLENGE_TOKEN 会在 /.well-known/openai-apps-challenge 提供 OpenAI 插件目录的域名验证令牌,响应内容仅为纯文本。未设置时,不会注册该路由,该路径会返回 404。

启动日志会输出一行已解析的配置(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 等);交换失败时,日志会附带仪表板返回的状态码和被调用的主机。令牌验证通过后,调用方会以令牌的 subject 显示,绝不会以凭据形式显示:访问令牌、Authorization header 和生成的 API 密钥都不会被记录。

服务器向 Skycloak API 发送的内容

托管服务器和本地二进制文件向 Skycloak API 发送相同的 header(SKYCLOAK_ENDPOINT):

Header值用途
API-Key你的 API 密钥或会话生成的密钥对请求进行身份验证
API-VersionSKYCLOAK_API_VERSION固定服务器所依据的 API 契约版本
User-Agentskycloak-mcp/<version>标识客户端
X-MCP-Tool工具注册名称,例如 skycloak_list_realms指明发起请求的工具
X-MCP-Call-Id每次工具调用生成一次的随机 UUID将同一次调用中的所有请求关联起来

只有在处理工具调用时发出的请求才会携带 X-MCP-Tool 和 X-MCP-Call-Id。一次调用可能会发出多个请求:当省略 cluster_id 时,每个集群各发出一次;如果重试 429 或 5xx,也会再次发出请求;这些请求都会共享该调用的 ID。Skycloak 使用这对标识统计各工具的使用频率,以帮助我们决定改进、编写文档或弃用哪些工具。它们不包含参数、结果或任何超出 API 密钥本身所能识别范围的个人信息,并且只会发送到 Skycloak API,绝不会发送到你的 Keycloak 集群或其他任何地方。工具调用之外发出的请求(例如登录和生成 API 密钥)不会携带这两个标识。

配置

环境变量默认值
SKYCLOAK_API_KEY无(stdio 可选;HTTP 客户端改为提供 API-Key headers)
SKYCLOAK_ENDPOINThttps://api.skycloak.io
SKYCLOAK_API_VERSION当前 API 版本
SKYCLOAK_ISSUERhttps://login.app.skycloak.io/realms/skycloak(CLI 登录,以及 HTTP 传输用于验证令牌的授权服务器)
SKYCLOAK_CLIENT_IDskycloak-mcp(仅限 CLI 设备授权流程)
SKYCLOAK_DASHBOARD_URLhttps://app.skycloak.io(生成 CLI 密钥和 HTTP 会话密钥)
SKYCLOAK_PUBLIC_URL无(根据每个请求推导;如果 ingress 会重写 Host,请设置此项)
OPENAI_APPS_CHALLENGE_TOKEN在 /.well-known/openai-apps-challenge 提供 OpenAI 插件目录验证令牌。未设置时,该路径会返回 404。

命令:init(浏览器登录)、run(启动服务)、logout(移除已存储的密钥)。init 接受 --workspace <id>、--allow-writes、--allow-credentials 和 --ttl-days(默认值为 90)。

标志默认值说明
--transportstdiostdio 或 http
--http-addr:8080HTTP 传输的监听地址
--allow-writesfalse为 stdio 启用可变更工具,并允许带有 readonly=false 的 HTTP 会话注册写入工具

开发

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 容器镜像,并以 io.skycloak/skycloak-mcp 的名称发布到 MCP Registry。大多数人无需使用这两种方式:托管服务器无需安装。

插件包

plugins/skycloak/ 是一个同时服务两个客户端的文件夹:Antigravity 使用 .antigravity-plugin/plugin.json 和 mcp_config.json,Claude 使用 .claude-plugin/plugin.json。两者都指向托管服务器,并附带四项技能;这些技能与 internal/tools/skills/ 完全逐字节相同,因为安装程序只会收到该文件夹。 仓库根目录下的 plugin.json 和 mcp.json 是 Agent Plugins v1.0.0 清单,GitHub 的 awesome-copilot 市场会读取这些清单。该格式不允许设置 logo 字段,因此列表中的 logo 通过 extensions["com.github.copilot"] 提供。

这些清单以及 .grok-plugin/plugin.json 中的 version 字段由 CI 根据发布标签设置,因为目录列表会跟踪 main。插件 README 中的目录更新部分对此有说明。

安全

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

贡献者

由 Guilliano Molaire、Neville Omangi 和 Aphilas 在 Skycloak 构建。仓库公开时, 提交历史经过了压缩,因此提交日志无法反映每个人的具体贡献。

许可证

Apache-2.0。internal/apiclient/openapi.yaml 中的 OpenAPI 描述由 Skycloak 平台 API 生成,版权归 Skycloak 所有;此处包含该描述,以便生成和验证客户端。请参阅 NOTICE。