mrz1880/mcp-keycloak-admin

A Model Context Protocol (MCP) server to
administer a Keycloak instance through its Admin
REST API. Safe by default, configurable, and built with a clean, test-driven
architecture.
Compatible with **Keycloak 26.x** (validated against 26.0.5).
Install
No install needed — run it straight from npm with npx:
The server speaks MCP over stdio, so you normally wire it into an MCP client
rather than running it by hand — see Usage with an MCP client.
New to it? The Quickstart spins up a local Keycloak and a
client config in a couple of minutes.
Why
Administering Keycloak from an MCP client (an assistant, an IDE, a custom agent)
means exposing day-to-day operations — searching users, managing roles, reading
events — as MCP tools, without handing over a raw admin console. This server
does that with strong guardrails so destructive actions never happen silently.
Features
- **Two authentication modes**, selectable by configuration:
- service_account — a confidential client with a service account
(recommended; no admin password stored).
- password — the admin-cli client with an admin username/password.
- **Safe by default:**
- READ_ONLY mode hides every write/destructive tool.
- ALLOWED_REALMS restricts which realms the server may operate on.
- Destructive operations require explicit confirmation (native MCP
elicitation, with a confirm: true parameter fallback for clients that do
not support elicitation).
- **Clean Architecture**: a framework-free domain, application use cases, and
infrastructure adapters. No business concept travels as a raw string or
number — every one is a validated value object.
Requirements
- Node.js >= 20
- A reachable Keycloak 26.x server
Usage with an MCP client
Add the server to your MCP client configuration:
See docs/setup-keycloak.md to create the mcp-admin
client and grant it the least-privilege roles it needs.
Multiple Keycloak instances
Each server entry targets **one** Keycloak (one base URL + realm + auth). To
manage several environments, add **one entry per instance** — each fully
isolated, with its own credentials and guardrails:
The client namespaces the tools per server (e.g. kc-prod:keycloak_user_delete),
so there's no risk of running an operation against the wrong environment. This
is the recommended pattern: you can, for example, keep production READ_ONLY
while preprod stays writable.
Configuration
| Variable | Required | Description |
| ------------------- | --------------------- | -------------------------------------------------------- |
| KEYCLOAK_BASE_URL | yes | Base URL of the Keycloak server (no trailing slash). |
| KEYCLOAK_REALM | yes | Realm the server operates on. |
| AUTH_MODE | yes | service_account or password. |
| KC_CLIENT_ID | if service_account | Confidential client id (e.g. mcp-admin). |
| KC_CLIENT_SECRET | if service_account | Client secret. |
| KC_ADMIN_USERNAME | if password | Admin username. |
| KC_ADMIN_PASSWORD | if password | Admin password. |
| KC_ADMIN_REALM | no (default master) | Realm holding the admin user (password mode). |
| READ_ONLY | no (default false) | When true, write/destructive tools are not registered. |
| ALLOWED_REALMS | no | Comma-separated allow-list of realms. Empty = all. |
A full example lives in .env.example.
Tools
Levels: **[R]** read-only · **[W]** write · **[D]** destructive (requires
confirmation). Every tool carries the matching MCP annotations
(readOnlyHint / destructiveHint / idempotentHint).
Currently implemented:
> **Note:** this table tracks the main branch, which can run ahead of the
> latest npm release shown by the version badge above. To confirm what's