KeyCloak MCP

keycloak-mcp

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.

Features

Users

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)

MFA / Credentials

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)

Groups

Tool	Description
list_user_groups	Which groups a user belongs to
list_users_by_group	Members of a group

Security

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_config_changes	What changed in the realm configuration since a stored daily snapshot (see Configuration snapshots). Read-only; baseline_date picks an older snapshot.
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.
spray_check	Password-spray detection with the breach list built in: every external IP with ≥ 10 distinct users and < 20 % login success is a spray source, and its successful logins (evidence tuple time / ip / username / user_id / client_id) are the breach candidates. Each row carries a confidence: high is a breach verdict; low means the volume rule fired on a shared egress (school NAT, home line, VDI) — signalled by user_success_rate (distinct users that logged in ÷ distinct users, ≥ 0.2), failure_concentration (share of failures on one username, ≥ 0.5) or a KEYCLOAK_KNOWN_EGRESS match — and the logins are to be verified with the owner, not published. top_failed_users and not_found_domains show who kept failing and which mistyped domains produced user_not_found. Fixed-shape JSON, complete: false when the window was truncated.
detect_login_loops	Flag users who logged in too many times in a short window (redirect loops)

Events

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

Admin Events

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.

Sessions & Clients

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_client	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

Morning Patrol

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, spray check (same rule as spray_check, with breached accounts and evidence), active sessions, password updates, admin events, and configuration changes (admin events on roles, role mappings, flows, client scopes, protocol mappers, components and the realm, plus the snapshot comparison when KEYCLOAK_STATE_DIR is set; both are flagged [CONFIG]), and additions to groups that carry roles (flagged [PRIVILEGE] when the group grants a realm-management role other than the read-only query-*/view-*) in a single Markdown summary. IPs exceeding ip_failure_threshold failures (default 50) and spray sources are flagged WARNING; API errors surface as CRITICAL. since_hours controls the look-back window (default 18 h).

Setup

# uv
uv pip install keycloak-mcp

# pip
pip install keycloak-mcp

From source:

git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp

# uv
uv sync

# pip
pip install -e .

Configuration

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_KNOWN_EGRESS	Comma-separated CIDRs of known shared egress points (VDI, VPN concentrators, partner proxies). spray_check labels matching IPs known_egress: true and marks them confidence: low; they are never excluded	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. Each request's timeout is also capped at the time left, and nothing is retried past the deadline, so one slow page cannot run a call past it. 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
KEYCLOAK_GROUP_WRITE_ROOT	Enables the opt-in group-change tools (plan_group_changes, apply_group_changes) and confines them to groups below this absolute path (e.g. /Staff). Unset, empty or malformed: the two tools are not registered at all. Set it only on a deployment that puts a human approval step in front of the server.	unset
KEYCLOAK_PROTECTED_GROUPS	;-separated full group paths that the group-change tools refuse to add to or remove from (descendants included). A malformed entry disables the group-change tools rather than silently dropping the protection.	unset
KEYCLOAK_GROUP_BATCH_MAX	Maximum rows per group-change call.	30
KEYCLOAK_GROUP_MODE	multi (KeyCloak's default: a user can be in many groups) or single for a deployment where adding a group replaces every other membership (for example an event listener that keeps one group per user). Any other value disables the group tools. See Group changes.	multi
KEYCLOAK_STATE_DIR	Directory for the daily configuration snapshots (<dir>/config-snapshots, created 0700, files 0600). Unset: no snapshots; daily_brief still reports configuration admin events. See Configuration snapshots.	unset
KEYCLOAK_GROUP_DEADLINE	Time budget (seconds) for the group-change tools. A batch of 30 users needs more than the default 45 s; raise it where nothing with a ~60 s timeout sits in front of the server (for example a client that spawns it directly). Unset: KEYCLOAK_DEADLINE.	unset

KeyCloak client setup

1. Create a new client in the KeyCloak admin console.
2. Turn on Client authentication and Service account roles.
3. Give it view-users, view-events, view-clients, and — only if you need password reset — manage-users.

Write operations

Four tools change state by default. Everything else only reads. With group changes enabled (below), apply_group_changes is a fifth.

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.

Group changes (opt-in)

plan_group_changes and apply_group_changes move users between groups (for example staff transfers). They exist only when KEYCLOAK_GROUP_WRITE_ROOT is set, so a deployment that shares the binary without an approval step never exposes them.

Tool	Admin API call
plan_group_changes	read-only: GET /users?username=...&exact=true, GET /group-by-path/..., GET /groups/{id}/role-mappings, GET /roles-by-id/{id}/composites, GET /clients/{id}, GET /users/{id}/groups
apply_group_changes	PUT /users/{id}/groups/{groupId} then DELETE /users/{id}/groups/{groupId}

• plan_group_changes resolves every user and group by exact name/path and returns, per row, the current direct groups, the operations that would run and a status. Its digest covers the resolved IDs, each user's current groups and the policy.
• apply_group_changes re-plans and changes nothing unless every row is still executable and the digest equals the approved one, so a membership changed by anyone since the plan aborts the whole batch. It adds before it removes, vets the destination again right before adding, re-reads memberships before each write and reads them back after it, and stops at the first mismatch, error or exhausted time budget (KEYCLOAK_GROUP_DEADLINE). It does not start a user whose operations cannot all finish in the time left, so a stop does not split an add from its remove. applied is yes, no, partial or unknown (a write that could not be read back).
• With KEYCLOAK_GROUP_MODE=single a move is one add: the server drops the old group itself, so no DELETE is sent and the read-back must show the destination alone. A row must name the group to add (a remove-only row would leave the user in no group). An omitted remove is filled in with the user's current group so the approver sees what is left, and that group is vetted like a remove at plan time and again right before the add. A user in more than one group breaks the server's rule and is refused (fix them by hand). Users whose previous state a plan cannot restore (they had no group, or the server turned out not to replace) are listed in manual_restore instead of reverse. Set it when your KeyCloak behaves this way; in multi mode such a server makes every move stop as a concurrent change, and in single mode a server that keeps the old group makes the move stop with a message that the mode does not match.
• Refused targets: anything outside the root, the root itself, and protected groups and their descendants.
• A group that carries roles is not refused: moving someone into a department's admin group is an ordinary transfer when the approver can do the same in the admin console. Each plan row lists gained_roles and lost_roles: the difference the move makes to the roles the user holds through all their group memberships (a role kept through a shared ancestor or another group is neither; roles mapped to the user directly are not read). add_roles and remove_roles are the roles membership in each named group carries. Realm roles appear by name and client roles as client:role; roles inherited from ancestor groups and the contents of composite roles (any depth) are included. Show the gains and losses to the person approving. They are part of the digest, and the destination's roles are read again before each add (at most once every 5 seconds per group within one call), so a role attached (or added to a composite) after the approval stops the run. A row whose role change cannot be shown (a current group that does not resolve by path, such as one with / in its name) is refused. Changed in 1.3.0: earlier versions refused any group with role mappings. If you relied on that, list those groups in KEYCLOAK_PROTECTED_GROUPS before upgrading.
• Membership can grant access without any role (a SAML/OIDC group mapper that a service provider checks, an authorization-services group policy). List the groups that must never be written by these tools, whatever their roles, in KEYCLOAK_PROTECTED_GROUPS. Every protected path must exist in KeyCloak: if one does not resolve (renamed, moved, different case), every plan is refused until the configuration is fixed.
• The digest shows that nothing changed since the plan. It does not prove that a person approved the plan: any caller of plan_group_changes gets a valid digest. Put the approval in front of apply_group_changes, for example a client that keeps the digest itself and asks a person before each call. Treat each approval as single-use: if the memberships return to the planned state (for example after reverse), the old digest matches again.
• The result includes reverse, the changes that would undo what took effect. It is a proposal for a new plan and approval, never applied automatically. Restoring a membership does not undo access that happened while it was wrong.

Writes need manage-users. Depending on the KeyCloak version, reading groups and their role mappings may also need query-groups. Expanding composite roles reads realm roles (view-realm) and naming client roles reads clients (view-clients). Run plan_group_changes once to confirm.

Configuration snapshots (optional)

With KEYCLOAK_STATE_DIR set, the first daily_brief of each day stores a snapshot of the realm configuration, and every daily_brief compares the current configuration with the latest snapshot from an earlier day. Changes are a [CONFIG] warning with the changed fields; get_config_changes lists all of them.

• Covered: realm settings (brute-force detection, password and OTP policies, session and token lifespans, flow bindings), event settings, realm roles and what each composite role contains, authentication flows and their executions, required actions, clients (redirect URIs, allowed flows, flow overrides, attributes, protocol mappers), client scopes, default client scopes, components, and identity providers when the service account may read them. Group role mappings and client roles are not in the snapshot; their admin events are reported instead.
• Group memberships are not configuration and are not in the snapshot. Instead the brief lists the additions in its look-back window to groups that carry a role (their own or an ancestor's, through composites), with the roles, the user, and who added them. An addition is [PRIVILEGE] when the group grants a realm-management role other than query-*/view-* (realm-admin, manage-users, ...); in the master realm also a <realm>-realm admin-client role or the admin realm role. The group is read by its ID as it is now and its roles are followed through parentId, so a rename or move since the event does not hide it. An addition whose group cannot be read is a [CONFIG] warning of its own; the check has at most 8 s of the Configuration section's budget.
• Secrets are not stored: string values under keys containing secret, password, privateKey, apiKey, credential, token and similar (the markers get_user also uses) are replaced with <redacted>, so a changed secret does not show as a change. true/false and numbers under such keys are settings and stay visible, except under a field that is itself a secret (...password, ...secret). This is a safety net for the common names, not a guarantee. Long values (certificates, public keys) are stored as a hash.
• Only a complete read is stored. When the time budget runs out, the brief says the comparison was skipped and the previous baseline stays.
• Snapshots are written only by daily_brief, and only the first one of a day, so a change made during the day is reported again the next morning. The last 30 are kept.
• Reading the configuration needs view-realm and view-clients; identity providers also need view-identity-providers. Without it that section is left out of the comparison and the brief says so.

Verify your setup

After setting the environment variables, run --check to confirm authentication works before wiring it into an MCP client:

export KEYCLOAK_URL=https://keycloak.example.com
export KEYCLOAK_REALM=my-realm
export KEYCLOAK_CLIENT_ID=keycloak-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
keycloak-mcp --check
# HTTP Request: POST https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token "HTTP/1.1 200 OK"
# OK: authenticated to https://keycloak.example.com/admin/realms/my-realm

Exit codes: 0 success, 1 configuration error (missing variable), 2 authentication error.

IP-to-site labeling (optional)

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:

[hq]
name = HQ (Tokyo)
ipv4 = 192.0.2.0/24, 198.51.100.0/24
ipv6 = 2001:db8:1::/48

[vpn]
name = VPN
ipv4 = 10.0.0.0/8, 172.16.0.0/12

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.

Usage

Claude Code (plugin)

This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:

/plugin marketplace add shigechika/keycloak-mcp
/plugin install keycloak-mcp@keycloak-mcp

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.

Claude Code (manual)

In .mcp.json:

{
  "mcpServers": {
    "keycloak-mcp": {
      "type": "stdio",
      "command": "keycloak-mcp",
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_REALM": "my-realm",
        "KEYCLOAK_CLIENT_ID": "keycloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": ""
      }
    }
  }
}

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak-mcp": {
      "command": "keycloak-mcp",
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_REALM": "my-realm",
        "KEYCLOAK_CLIENT_ID": "keycloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": ""
      }
    }
  }
}

From a shell

export KEYCLOAK_URL=https://keycloak.example.com
export KEYCLOAK_REALM=my-realm
export KEYCLOAK_CLIENT_ID=keycloak-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
keycloak-mcp

CLI

keycloak-mcp --version   # Print version and exit
keycloak-mcp --help      # Show usage and required environment variables
keycloak-mcp --check     # Verify env vars and authentication, then exit
keycloak-mcp             # Run the MCP STDIO server (default)

No-argument mode is the normal one — that's how MCP clients launch it.

Daily spray report (batch)

spray_check looks at a rolling window ending now, which is right for a patrol but cannot be archived day by day. For that, run the same analysis over one calendar day from a scheduled job:

keycloak-mcp spray-report --date 2026-09-17 --tz Asia/Tokyo > 2026-09-17.json

• The window is [DATE 00:00, DATE+1 00:00) in --tz (default: the host's zone). Use the zone the KeyCloak server logs in, because dateFrom / dateTo are interpreted there. Events are cut to the window by timestamp on both ends.
• One JSON document goes to stdout; errors go to stderr with a non-zero exit (2 = configuration, 1 = fetch/auth), and nothing is written to stdout in that case.
• The output is the spray_check shape with every external IP that has at least one event carrying a username in external_ips (min_report_users=1), plus external_totals, which counts LOGIN / LOGIN_ERROR for every external IP — including IPs whose failures carry no username at all and therefore have no row, fetch_complete, resolve_complete, coverage (first_event, last_event, head_gap_seconds, tail_gap_seconds), schema, keycloak_mcp_version and sites_ini_sha256. Treat a day as final only when both *_complete flags are true and neither gap is large; a gap at one end usually means --tz differs from the KeyCloak server's zone.
• It refuses to run when KEYCLOAK_SITES_INI yields no ranges (every IP would count as external) unless --allow-no-sites is given, and when KEYCLOAK_KNOWN_EGRESS has an entry that is not a CIDR.
• Its own limits apply (--deadline 900, --max-events 1000000, --max-resolves 2000), not KEYCLOAK_DEADLINE / KEYCLOAK_MAX_EVENTS, which are sized for a tool call behind an HTTP gateway.
• The output contains source IPs and usernames. Keep it out of anything published.

Development

git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp

# uv
uv sync --dev
uv run pytest -v
uv run ruff check .

# pip
python3 -m venv .venv
.venv/bin/pip install -e . && .venv/bin/pip install pytest pytest-cov respx ruff
.venv/bin/pytest -v
.venv/bin/ruff check .

Live smoke test

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:

# needs KEYCLOAK_URL / KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only login_stats --traceback

• Read-only. Every state-changing tool (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.
• Arguments that would identify real users, groups or IPs are discovered at run time, never written into scripts/smoke_probes.py.
• CI enforces the cheap half: a tool registered without a probe spec fails the build (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.

License

MIT