Skycloak

skycloak-mcp

Official Model Context Protocol server for Skycloak (managed Keycloak): manage your clusters, realms, applications, and SSO from any MCP client (Claude Desktop, Claude Code, Cursor).

Status: early release. Tool coverage is growing; see the changelog for what's available.

Quick start

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

No API key, no client ID, no configuration. Your browser opens, you sign in to Skycloak, and the tools appear. Any MCP client that speaks streamable HTTP works the same way: give it the URL and nothing else.

Then ask for something:

• "Which of my Keycloak clusters are behind on upgrades?"
• "Create a staging realm on the EU cluster with Google and GitHub sign-in."
• "Who was added to the production realm in the last week?"
• "Set up a SIEM destination that forwards admin events to our Datadog webhook."

Authentication & safety

• Hosted HTTP, with OAuth (no credential to configure). Point your client at https://mcp.skycloak.io with no header. The server answers 401 with a pointer to its RFC 9728 metadata at /.well-known/oauth-protected-resource, the client runs the browser authorization-code flow against the Skycloak login realm, and the access token it gets back is exchanged for a short-lived, workspace-scoped API key that the session runs on. The key lasts an hour and is renewed automatically. Nothing is stored in your client configuration.
• Hosted HTTP, with an API key. Create a key in the Skycloak dashboard and send it as Authorization: Bearer (or API-Key: ). Every request carries its own credential and acts only as that credential's workspace. The server keeps no session state, so a request never inherits another caller's. Keys are not verified before use: the Skycloak API is the authority, so an invalid key surfaces as a 401 on the first tool call rather than at connect time.
• Tools match your role. Over OAuth, the tool list is trimmed to what the session's scopes allow, so a read-only workspace member is not shown write tools that would answer 403. With an API key the whole surface is registered, because a key's scopes are not visible to the server, and an unauthorized call surfaces as a 403 from the API.
• Local stdio. Run skycloak-mcp init and approve in your browser (OAuth 2.0 device authorization flow). It mints a workspace-scoped API key, stores it in your operating-system keychain, and detects your default workspace automatically (pass --workspace to pick another). skycloak-mcp logout removes the stored key.
• Headless / CI. Set the SKYCLOAK_API_KEY environment variable (create a key in the Skycloak dashboard) to skip the browser entirely. It always takes precedence over the keychain.
• Writes are gated by your credential, not by a flag. The hosted server at https://mcp.skycloak.io runs write-capable, and what you can actually change is bounded by your key's scopes and your workspace role: a read-only member cannot mutate anything, whatever the tool list says. Add ?readonly=true to the URL to force a read-only tool surface for a session. The local binary is the opposite way round and registers no write tools unless started with --allow-writes.
• Cluster credentials are opt-in. get_cluster_credentials returns a cluster's Keycloak admin credentials, which an assistant holding the key would then see, so init does not request that scope by default. Use a key that carries it: create one in the dashboard, or over stdio sign in with skycloak-mcp init --allow-credentials. Without it the tool returns a 403 that explains both routes.
• Destructive tools require confirmation: deleting a realm, for example, needs an explicit confirm=true argument.
• Requests are rate limited according to your Skycloak plan; on a 429 response the server surfaces Retry-After.

Tools

137 tools: 60 read-only and 77 write. Read-only tools are always available. On the hosted server the write tools are registered too and gated by your credential's scopes; the local binary registers them only when started with --allow-writes.

Tool names carry a skycloak_ prefix that the table below omits, so list_clusters is skycloak_list_clusters in your client.

Conventions: destructive tools (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) require confirm=true. update_theme_settings turns exact_theme_names on or off for the workspace; the caller's API key must have been minted for a workspace owner or admin, or it gets 403 even with themes:write. Turning it on moves existing themes to their exact served names in the background; a theme whose content was replaced under its exact name reports restart_required: true from get_theme/list_themes/update_theme_content until restart_cluster_instances rolls that cluster's Keycloak instances. A restart may be deferred to the cluster's maintenance window instead of applying immediately, reported as deferred: true and, when known, next_window. create_cluster is asynchronous: poll get_cluster until the cluster is available. create_domain returns the DNS records the customer must create; verify_domain triggers a DNS check. set_theme_assignment activates a custom theme per Keycloak theme type (empty string resets to the built-in default). update_theme_content replaces a theme's archive in place (base64 ZIP or Keycloakify JAR in content_base64), keeping the theme's ID, name and realm and application assignments, so editing a theme no longer means deleting and re-uploading it; it needs confirm=true because the archive it overwrites is not recoverable, and update_theme still changes only the name, description and version. See docs/theme-content-update.md for how that call is made. update_cluster_security leaves CAPTCHA settings untouched. Realm import/export moves one realm's configuration and is separate from create_export, which dumps a whole cluster's database: both are asynchronous, and the realm archive is always encrypted, so the password used to export it is needed to import it again. A realm can be imported straight from an existing export (source_export_id) or from an uploaded archive (create_realm_import_upload_url, PUT, then upload_s3_key); importing creates a realm and refuses a name collision rather than overwriting, and needs confirm=true because it brings users and credentials with it.

Cluster locations: location on create_cluster, and in what list_clusters, get_cluster and list_cluster_locations return, is one of us (US East), us-west (US West), ca (Canada), eu (Europe) or au (Australia), in any case. us always means US East. us-west is only open to workspaces that have been granted access to it: list_cluster_locations lists every location with available set for your workspace, and creating a cluster in a location you cannot use returns the API's 400 "location not available".

Prompts

Eight prompts give you a starting point into that tool surface. Clients surface them as slash commands or suggested actions; each one takes arguments (realm, cluster, time window) and walks the model through the right tools in the right order.

Prompts are gated the same way as the tool