The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the KeyCloak MCP listing page.
English | 日本語
An MCP (Model Context Protocol) server for the KeyCloak Admin REST API.
Documentation: https://shigechika.github.io/keycloak-mcp/
Authenticates via a Service Account (Client Credentials Grant), so no human password or TOTP is involved. Also Infinispan-safe — it never creates user sessions and never hits the userinfo endpoint.
| Tool | Description |
|---|---|
count_users | Total user count in the realm |
search_users | Partial-match search (username / email / name) |
get_user | Full detail for an exact username |
reset_password | Reset one user's password |
reset_passwords_batch | Bulk reset from CSV (username,password per line; blank password is generated) |
get_user_sessions | Active sessions for one user, timestamps in local time |
logout_user | Kill all active sessions for one user |
set_user_enabled | Enable or disable one user; disabling blocks all logins (custom attributes preserved) |
| Tool | Description |
|---|---|
get_user_credentials | Credential types configured for one user; an otp entry means TOTP/HOTP is set up |
get_totp_users | Realm-wide TOTP adoption: how many users have an otp credential, with percentage and (optionally) the user list. Enumerates users and reads each one's credentials (N+1; bound with max_users) |
| Tool | Description |
|---|---|
list_user_groups | Which groups a user belongs to |
list_users_by_group | Members of a group |
| Tool | Description |
|---|---|
get_brute_force_status | Whether a user is currently locked by brute-force detection |
get_realm_security_defenses | Realm-level security policy: whether brute-force detection is enabled and its thresholds, the password policy, and browser security headers |
get_login_failures_by_ip | Failure breakdown by source IP (site-labeled when KEYCLOAK_SITES_INI is set) |
get_ip_activity | Exhaustive investigation of one source IP: success/failure counts, affected users/clients, timeline. Returns structured JSON. |
detect_login_loops | Flag users who logged in too many times in a short window (redirect loops) |
| Tool | Description |
|---|---|
get_events | Filter by type, username, client, IP, and date range. Username is resolved to user ID internally. Failure events include KeyCloak's error field (e.g. invalid_user_credentials). |
get_login_stats | Login success/failure totals, paginated across all results |
get_login_stats_by_hour | Logins bucketed by hour of day (local time) |
get_login_stats_by_client | Logins bucketed by client / SP |
get_password_update_events | UPDATE_PASSWORD history |
get_events only sees user events. Actions driven by an admin — or by a service account writing custom attributes — don't show up there. The admin-event endpoint fills that gap.
| Tool | Description |
|---|---|
get_admin_events | Filter by operation (CREATE / UPDATE / DELETE / ACTION), resource type (USER / CLIENT / ROLE / GROUP / …), resource path, and date range |
get_user_attribute_history | UPDATE/ACTION events scoped to one user — handy for tracking when a custom attribute (e.g. provisioning_flag) was written by an automated pipeline |
Both tools accept max_repr to control the representation payload: positive = truncate to N chars (default 500), 0 = omit, negative = include in full.
| Tool | Description |
|---|---|
get_session_stats | Active session count per client |
get_client_sessions | Active sessions for one client (SP) |
list_clients | SAML and OIDC clients in the realm |
get_realm_roles | Realm-level roles |
| Tool | Description |
|---|---|
health_check | Report the running server version and verify the KeyCloak backend is reachable and the service account can authenticate. Lightweight (one token request; no user/event/session scans). Returns a fixed-shape dict with status, auth, and the configured URL/realm. The tool's own description enumerates the values those fields can take, and is the one place that does. |
daily_brief | One-shot morning health check: login stats, brute-force IPs, active sessions, password updates, and admin events in a single Markdown summary. IPs exceeding ip_failure_threshold failures (default 50) are flagged WARNING; API errors surface as CRITICAL. since_hours controls the look-back window (default 18 h). |
From source:
| Variable | Description | Default |
|---|---|---|
KEYCLOAK_URL | Base URL, e.g. https://keycloak.example.com | required |
KEYCLOAK_REALM | Realm name | master |
KEYCLOAK_CLIENT_ID | Service Account client ID | required |
KEYCLOAK_CLIENT_SECRET | Client secret | required |
KEYCLOAK_SITES_INI | INI file for IP-to-site labeling (see below) | unset |
KEYCLOAK_DEFAULT_DATE_FROM_HOURS | Default look-back window for event tools when date_from is omitted. Set to 0 to scan full history (can hang on large realms). | 24 |
KEYCLOAK_DEADLINE | Per-call wall-clock budget (seconds) for the heavy event/TOTP tools. When a wide window / large realm would exceed it, the tool stops and returns a disclosed partial (⚠️ warning) instead of running past the client's ~60s gateway timeout and hammering KeyCloak. 0 or negative disables. | 45 |
KEYCLOAK_MAX_EVENTS | Per-pagination cap on events fetched by the event tools (also bounds how deep the slow high-offset pagination goes). Over the cap the result is a disclosed partial. 0 or negative disables. | 200000 |
KEYCLOAK_MAX_USERS | Default cap on users scanned by get_totp_users when its max_users argument is 0 (each user costs one credential call). 0 or negative disables (whole realm, bounded only by KEYCLOAK_DEADLINE). | 5000 |
KEYCLOAK_USER_ATTRIBUTE_WHITELIST | Comma-separated custom user-attribute keys that get_user is allowed to surface. Unset by default: get_user only ever returns username/name/email/enabled/created, since the search endpoint it resolves the username through returns a brief representation with no attributes at all. Opting a key in makes get_user do one extra by-ID lookup and append that attribute's value when present. Everything else stays out of tool output. As a safety net, a whitelisted key whose name looks credential-shaped (contains password, secret, token, etc.) is reported as blocked rather than shown — not a guarantee, since a credential attribute named outside that pattern list still gets through. | unset |
view-users, view-events, view-clients, and — only if you need password reset — manage-users.Four tools change state. Everything else only reads.
| Tool | Admin API call |
|---|---|
reset_password | PUT /users/{id}/reset-password |
reset_passwords_batch | the same call, once per CSV row |
set_user_enabled | PUT /users/{id} with enabled toggled |
logout_user | POST /users/{id}/logout |
All four need manage-users on the Service Account. Leave that role off and the
server is read-only: those four tools fail with 403 and every other tool keeps
working, so a realm can be handed to Claude for investigation without granting any
ability to modify it. Grant manage-users only when account recovery or
containment is part of the job.
After setting the environment variables, run --check to confirm authentication works before wiring it into an MCP client:
Exit codes: 0 success, 1 configuration error (missing variable), 2 authentication error.
Point KEYCLOAK_SITES_INI at an INI file if you want IP addresses in tool output to be tagged with your site names. Tools like get_user_sessions, get_events, and get_login_failures_by_ip pick it up automatically; anything outside your declared ranges is labeled external. Leave the variable unset and IPs are shown as-is.
See sites.ini.example. A minimal file:
One site per [section]. name is the display label (falls back to the section name). ipv4 / ipv6 take comma-separated CIDRs; a single host is /32 or /128. Matching is first-match in file order — put specific ranges before broad ones.
This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:
The plugin launches uvx keycloak-mcp and reads the same environment variables
described in Configuration; export them before starting Claude
Code. KEYCLOAK_REALM falls back to master and KEYCLOAK_SITES_INI may stay
unset.
uvx must be on the PATH of the process that runs Claude Code — a login
shell usually has it, but a GUI-launched app may not; install
uv system-wide if the plugin fails to start.
In .mcp.json:
In claude_desktop_config.json:
No-argument mode is the normal one — that's how MCP clients launch it.
pytest checks logic against fixtures; it cannot tell you that a tool has
stopped returning real data. scripts/smoke_test.py runs every registered
tool against the configured realm and fails on empty, malformed or error
answers:
reset_password, logout_user,
set_user_enabled, reset_passwords_batch) is skipped by name, and a test
enforces that. The report prints tool names and statuses only — never
payloads, and server-authored error text is redacted too (KeyCloak quotes the
username it was asked about); --traceback still shows the full text on the
operator's own terminal.scripts/smoke_probes.py.tests/test_smoke_probes.py), so adding a tool forces the question
"how would we know it works?".scripts/smoke_harness.py is the engine and holds no KeyCloak knowledge:
it is kept identical across the servers that share it, so fix engine bugs
once and sync the file rather than patching this copy.MIT