Reference¶
health_check()¶
Seven keys are present on every call:
| Key | Meaning |
|---|---|
status |
healthy / degraded / error |
service |
Always keycloak-mcp |
version |
Package version |
keycloak_url |
Configured URL (empty string when unset) |
realm |
Configured realm (empty string when unset) |
keycloak_version |
Always null — not exposed by a cheap call |
auth |
unknown / ok / missing-env / error |
detail is added only on degraded or error, with the reason: a missing
environment variable, or the exception type (and HTTP status, when the
backend returned one) for a genuine authentication failure. Internal URLs and
raw HTTP payloads are deliberately kept out of it.
Lightweight by design: it acquires one Client Credentials token — the lightest possible proof the service account can talk to the realm — and scans nothing else. Safe to call at session start or after a tool-call timeout.
Tool index¶
| Tool | Purpose |
|---|---|
count_users |
Total user count in the realm |
search_users(query, max_results=20) |
Partial-match search: username, email, first/last name |
get_user(username) |
Full detail for an exact username |
get_user_sessions(username) |
Active sessions, timestamps in local time |
logout_user(username) |
Writes. Ends all active sessions for one user |
set_user_enabled(username, enabled) |
Writes. Enable/disable; disabling does not end existing sessions |
reset_password(username, password, temporary=False) |
Writes. Reset one user's password |
reset_passwords_batch(csv_text, temporary=False) |
Writes. Bulk reset from username,password CSV |
get_user_credentials(username) |
Configured credential types; an otp entry means TOTP/HOTP is set up |
get_totp_users(max_users=0) |
Realm-wide TOTP adoption. N+1 (one call per user); bounded by max_users or KEYCLOAK_MAX_USERS |
list_user_groups(username) |
Groups a user belongs to |
list_users_by_group(group_name, max_results=100) |
Members of a group |
plan_group_changes(changes) |
Opt-in, registered only when KEYCLOAK_GROUP_WRITE_ROOT is set. Read-only check of a batch of group moves (username, remove, add as full paths); returns per-row status, the net role gains and losses, and a digest to show a human for approval |
apply_group_changes(changes, expected_digest) |
Writes. Opt-in, registered only when KEYCLOAK_GROUP_WRITE_ROOT is set. Applies an approved plan: re-plans and changes nothing unless the fresh digest matches, then adds before removing per user with read-back; returns applied (yes / no / partial / unknown) and a reverse proposal. The digest is a staleness check, not an approval token |
get_brute_force_status(username) |
Whether a user is currently locked by brute-force detection |
get_realm_security_defenses() |
Brute-force policy and thresholds, password policy, browser security headers |
get_config_changes(baseline_date="") |
What changed in the realm configuration since a stored daily snapshot (needs KEYCLOAK_STATE_DIR; snapshots are written by daily_brief) |
get_login_failures_by_ip(date_from, date_to, top=20) |
Failure counts ranked by source IP |
get_ip_activity(ip_address, event_types, date_from, date_to, max_timeline=200) |
Exhaustive per-IP investigation (structured JSON) |
spray_check(hours=24, min_users=10, max_success_rate=0.2, min_report_users=3, max_resolves=200, max_user_success_rate=0.2, max_failure_concentration=0.5) |
Password-spray detection: external IPs with at least min_users distinct users and a success rate below max_success_rate, with their successful logins as breach candidates (evidence tuples). Only confidence: high rows are a breach verdict; low marks a shared egress or a KEYCLOAK_KNOWN_EGRESS match. Fixed-shape JSON; complete: false when the scan was cut short |
detect_login_loops(date_from, date_to, threshold=10, window_seconds=60, top=20) |
Users logging in faster than threshold per window_seconds |
get_events(event_type, username, client_id, ip_address, date_from, date_to, max_results=50) |
Filtered event search; username resolved to user ID internally |
get_login_stats(date_from, date_to) |
Success/failure totals, fully paginated |
get_login_stats_by_hour(date_from, date_to) |
Logins bucketed by hour of day, local time |
get_login_stats_by_client(date_from, date_to) |
Logins bucketed by client (SP) |
get_password_update_events(date_from, date_to, max_results=100) |
UPDATE_PASSWORD history |
get_admin_events(operation_types, resource_types, resource_path, date_from, date_to, max_results=50, max_repr=500) |
Admin-driven changes; get_events never sees these |
get_user_attribute_history(username, date_from, date_to, max_results=100, max_repr=500) |
Admin events scoped to one user |
get_session_stats() |
Active session count per client |
get_client_sessions(client_id, max_results=100) |
Active sessions for one client |
list_clients() |
SAML and OIDC clients in the realm |
get_client(client_id) |
One client's configuration, including its authentication flow overrides (the per-SP MFA switch). Omits attributes and protocolMappers, so no client secret or SAML signing material reaches tool output. |
get_realm_roles() |
Realm-level roles |
daily_brief(since_hours=18, ip_failure_threshold=50) |
Morning summary: login stats, brute-force IPs, spray check, sessions, password updates, admin events, configuration changes |
See Security investigation for what the write tools
actually do, how to read get_ip_activity's output, and the deadline /
partial-result mechanism shared by the heavy scans.
daily_brief¶
One Markdown report covering login stats, IPs over ip_failure_threshold
failures (flagged WARNING), a spray check (the spray_check rule; high-confidence
matches are flagged [SPRAY] with the breached accounts and their evidence,
low-confidence ones [SPRAY?] as logins to verify), active sessions, password updates, and admin
events, all within since_hours (default 18 — roughly the previous afternoon
for a 09:00 morning run). A Configuration section lists admin events on roles,
role mappings, flows, client scopes, protocol mappers, components and the realm,
and, with KEYCLOAK_STATE_DIR set, what changed since the latest daily snapshot
from an earlier day (both flagged [CONFIG]). The first brief of a day stores
that day's snapshot; secrets are redacted before anything is stored. Additions to
groups that carry roles are listed too, and flagged [PRIVILEGE] when the group grants
a realm-management role other than the read-only query-*/view-*. A backend connection failure renders the whole
report as ## CRITICAL — <ExceptionType> rather than a partial brief with
gaps unaccounted for.
get_admin_events and get_user_attribute_history accept max_repr, which
controls how much of the KeyCloak "representation" payload (the changed
object, as JSON text) is included: positive truncates to that many characters
(default 500), 0 omits it, negative includes it in full.
get_events vs. get_admin_events¶
get_events sees user events — logins, logouts, password changes performed
by the user themself. Actions performed by an administrator, or by a service
account writing a custom attribute, do not appear there at all;
get_admin_events is the endpoint that does. get_user_attribute_history is
get_admin_events pre-scoped to one user, useful for confirming when an
automated pipeline last wrote something like a provisioning_flag attribute.
CLI¶
keycloak-mcp # start the MCP server (stdio; default, no arguments)
keycloak-mcp --version # print version and exit
keycloak-mcp --help # show usage and required environment variables
keycloak-mcp --check # verify environment and authentication, then exit
Exit codes for --check: 0 success, 1 a required environment variable is
missing, 2 authentication failed.