dockndevai/mcp-keycloak

A Model Context Protocol server for **Keycloak**. It lets an MCP-capable client (Claude Desktop, Claude Code, etc.) inspect and manage Keycloak realms, users, clients, roles, and groups — with security controlled entirely by flags.
The design goal is **safe by default**: it starts read-only, scopes to an allowlist of realms, protects sensitive realms from mutation, and gates destructive operations behind an explicit opt-in.
Features
- **Multi-realm** — every tool takes a realm argument; scope it with an allowlist.
- **Access modes** — read-only → read-write → admin, layered so a mode never exposes tools above its level.
- **Security flags** — realm allowlist, protected realms, delete gating, dry-run, and JSON audit logging (see below).
- **Two auth strategies** — confidential-client service account (recommended) or admin username/password.
- **Zero heavy dependencies** — a thin fetch-based Admin REST client, plus the MCP SDK and zod.
Security model
| Concern | Flag | Default | Effect |
| --- | --- | --- | --- |
| What can the server do at all? | KEYCLOAK_MODE | read-only | read-only exposes only read tools; read-write adds mutations; admin adds destructive tools. Tools above the mode are **never registered**. |
| Which realms are in scope? | KEYCLOAK_REALM_ALLOWLIST | *(all)* | Comma-separated. When set, any operation on a realm outside the list is refused. |
| Which realms are read-only forever? | KEYCLOAK_PROTECTED_REALMS | master | Protected realms can be read but never mutated or deleted, regardless of mode. |
| Can it delete? | KEYCLOAK_ALLOW_DELETE | false | delete_* tools require this **and** admin mode. |
| Preview without touching Keycloak | KEYCLOAK_DRY_RUN | false | Write/admin tools validate + log intent, then return without calling Keycloak. |
| Audit trail | KEYCLOAK_AUDIT_LOG | true | Emits a JSON line to stderr per guarded operation (ALLOW / DENY / DRY_RUN). |
| Interactive confirmation | *(automatic)* | — | Destructive & high-impact actions prompt the human to approve via MCP elicitation before running; clients without elicitation fall back to the *_ALLOW_* gate. |
These layers are independent — for example admin mode with KEYCLOAK_ALLOW_DELETE=false can create and update users but cannot delete them.
Tools
**Read** (read-only+): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups
**Write** (read-write+): create_user, update_user, reset_password, logout_user
**Admin** (admin): delete_user
Quickstart — add to your agent
Published on npm as @dockndevai/mcp-keycloak. No clone or build needed — your MCP client runs it on demand with npx. **Start in read-only mode**; see .env.example for every variable and docs/CLIENTS.md for the full per-client guide.