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 <key> (or API-Key: <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 <id> 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

129 tools: 58 read-only and 71 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) require confirm=true. 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_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.

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.