skycloak-mcp

# skycloak-mcp

[![Smithery](https://img.shields.io/badge/Smithery-skycloak%2Fkeycloak--mcp-ea580c)](https://smithery.ai/servers/skycloak/keycloak-mcp)

Official [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
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](https://www.rfc-editor.org/rfc/rfc9728.html) 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](https://app.skycloak.io) 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](https://app.skycloak.io)) 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.

| Area | Read-only | Write (`--allow-writes`) |
|---|---|---|
| Clusters | `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_window` | `create_cluster`, `update_cluster`, `delete_cluster`, `cancel_cluster_upgrade`, `set_cluster_maintenance_window`, `delete_cluster_maintenance_window` |
| Edge security | `get_cluster_security`, `list_cluster_captcha_domains` | `update_cluster_security`, `add_cluster_captcha_domain`, `remove_cluster_captcha_domain` |
| Realms | `list_realms`, `get_realm` | `create_realm`, `update_realm`, `delete_realm` |
| Applications | `list_applications`, `get_application`, `list_application_roles`, `list_application_sessions` | `create_application`, `update_application`, `delete_application`, `assign_application_role`, `remove_application_role`, `rotate_application_secret` |
| Identity providers | `list_identity_providers`, `get_identity_provider`, `list_identity_provider_templates`, `discover_oidc` | `create_identity_provider` (OIDC), `update_identity_provider`, `delete_identity_provider`, `test_identity_provider` |
| Users, roles & groups | `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_groups` | `create_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` |
| Custom domains | `list_domains`, `get_domain`, `list_domain_routes`, `get_domain_route` | `create_domain`, `verify_domain`, `delete_domain`, `create_domain_route`, `update_domain_route`, `delete_domain_route` |
| Branding & themes | `list_themes`, `get_theme`, `get_theme_assignment`, `get_client_theme_assignment`, `get_login_branding`, `get_email_branding`, `download_theme_content` | `set_theme_assignment`, `set_client_theme_assignment`, `update_theme`, `delete_theme`, `upsert_login_branding`, `delete_login_branding`, `upsert_email_branding`, `delete_email_branding` |
| Extensions | `list_extensions`, `list_cluster_extensions` | `install_extension`, `upgrade_extension`, `update_extension`, `uninstall_extension`, `delete_extension` |
| SMTP | `get_smtp` | `upsert_smtp`, `delete_smtp`, `test_smtp` |
| Exports & logs | `list_exports`, `get_export`, `get_logs`, `get_security_logs`, `query_events` | `create_export`, `delete_export`, `export_cluster_events` |
| Realm import & export | `get_realm_export`, `get_realm_import` | `create_realm_export`, `create_realm_import`, `create_realm_import_upload_url` |
| SIEM | `list_siem_destinations`, `get_siem_destination` | `create_siem_destination`, `update_siem_destination`, `delete_siem_destination`, `test_siem_destination` |
| Webhooks | `list_webhook_event_types`, `list_webhook_subscriptions`, `get_webhook_subscription` | `create_webhook_subscription`, `update_webhook_subscription`, `delete_webhook_subscription`, `test_webhook_subscription` |

**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.

| Prompt | What it does |
|---|---|
| `audit_self_registration` | Find every realm that still allows self-registration, across one cluster or all of them |
| `review_upgrades` | Spot clusters behind on their Keycloak version and lay out the upgrade path |
| `triage_failed_logins` | Pull recent failed logins for a realm and group them by source IP |
| `review_identity_providers` | List a realm's SSO connections and check whether a specific one is enabled |
| `review_admin_changes` | Show who changed what in a realm recently, focused on login and security settings |
| `provision_environment` | Create a cluster, add a realm, and wire up an identity provider, confirming each step |
| `set_up_custom_domain` | Add a custom domain, hand back the exact DNS records, verify, and route it to a realm |
| `rotate_