KeyCloak MCP

io.github.shigechika由 GitHub 帳號 shigechika 發布v1.5.1更新於 Oct 30, 2026

MCP server for KeyCloak Admin REST API via Service Account

已驗證STDIO僅桌面開發者工具安全與監控

概覽

AI 產生的概覽

面向 KeyCloak Admin REST API 的本機 MCP 伺服器，讓助理檢視使用者、工作階段、用戶端與登入事件，並可選擇重設密碼或停用帳號。

可以做什麼
  • 檢視使用者：統計數量、搜尋、讀取詳細資料、列出所屬群組、檢查憑證類型與 TOTP 覆蓋率、查詢暴力破解鎖定狀態
  • 檢視工作階段與用戶端：依使用者或用戶端列出作用中工作階段、強制登出、列出 SAML/OIDC 用戶端與領域角色
  • 分析事件：依小時、用戶端或 IP 統計登入成功與失敗，查詢密碼變更事件、管理員事件與單一使用者的屬性變更紀錄
  • 安全調查：完整追查單一 IP 的活動、偵測密碼噴灑並列出疑似遭入侵帳號、偵測登入迴圈、檢視領域安全防護設定
  • 變更帳號（寫入操作）：重設單一或批次密碼、啟用或停用使用者
  • 晨間巡檢：健康檢查，以及一份彙整登入、噴灑來源、工作階段與設定變更的 Markdown 簡報
適用情境
適合身分與 IT 管理員讓助理查詢 KeyCloak 領域狀態、調查可疑登入或密碼噴灑，並執行日常的帳號復原與處置。可用於唯讀調查，也可在服務帳號被授予 manage-users 後進行受控的寫入操作。
執行需求
以 Python 套件形式（pip 或 uv 安裝）在本機透過 stdio 執行。需透過環境變數 KEYCLOAK_URL、KEYCLOAK_REALM、KEYCLOAK_CLIENT_ID 與 KEYCLOAK_CLIENT_SECRET 提供 KeyCloak 位址、領域、服務帳號用戶端 ID 與密鑰，並能連線至 KeyCloak 伺服器。服務帳號需具備 view-users、view-events、view-clients 等角色，寫入操作另需 manage-users。
安裝前請注意
KEYCLOAK_CLIENT_SECRET 是高權限憑證；僅在確有必要時授予 manage-users，未授予時伺服器維持唯讀。有四個工具會改變狀態：reset_password、reset_passwords_batch、set_user_enabled 與 logout_user；設定 KEYCLOAK_GROUP_WRITE_ROOT 後還會啟用群組變更工具。工具輸出包含使用者名稱、來源 IP 與事件資料，噴灑報告不應對外發布。KEYCLOAK_STATE_DIR 的快照會遮蔽常見密鑰欄位名稱，但並非萬無一失。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 KeyCloak MCP，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

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

ToolDescription
count_usersTotal user count in the realm
search_usersPartial-match search (username / email / name)
get_userFull detail for an exact username
reset_passwordReset one user's password
reset_passwords_batchBulk reset from CSV (username,password per line; blank password is generated)
get_user_sessionsActive sessions for one user, timestamps in local time
logout_userKill all active sessions for one user
set_user_enabledEnable or disable one user; disabling blocks all logins (custom attributes preserved)

MFA / Credentials

ToolDescription
get_user_credentialsCredential types configured for one user; an otp entry means TOTP/HOTP is set up
get_totp_usersRealm-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

ToolDescription
list_user_groupsWhich groups a user belongs to
list_users_by_groupMembers of a group

Security

ToolDescription
get_brute_force_statusWhether a user is currently locked by brute-force detection
get_realm_security_defensesRealm-level security policy: whether brute-force detection is enabled and its thresholds, the password policy, and browser security headers
get_config_changesWhat 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_ipFailure breakdown by source IP (site-labeled when KEYCLOAK_SITES_INI is set)
get_ip_activityExhaustive investigation of one source IP: success/failure counts, affected users/clients, timeline. Returns structured JSON.
spray_checkPassword-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_loopsFlag users who logged in too many times in a short window (redirect loops)

Events

ToolDescription
get_eventsFilter 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_statsLogin success/failure totals, paginated across all results
get_login_stats_by_hourLogins bucketed by hour of day (local time)
get_login_stats_by_clientLogins bucketed by client / SP
get_password_update_eventsUPDATE_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.

ToolDescription
get_admin_eventsFilter by operation (CREATE / UPDATE / DELETE / ACTION), resource type (USER / CLIENT / ROLE / GROUP / …), resource path, and date range
get_user_attribute_historyUPDATE/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

ToolDescription
get_session_statsActive session count per client
get_client_sessionsActive sessions for one client (SP)
list_clientsSAML and OIDC clients in the realm
get_clientOne 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_rolesRealm-level roles

Morning Patrol

ToolDescription
health_checkReport 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_briefOne-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

bash
# uvuv pip install keycloak-mcp
# pippip install keycloak-mcp

From source:

bash
git clone https://github.com/shigechika/keycloak-mcp.gitcd keycloak-mcp
# uvuv sync
# pippip install -e .

Configuration

VariableDescriptionDefault
KEYCLOAK_URLBase URL, e.g. https://keycloak.example.comrequired
KEYCLOAK_REALMRealm namemaster
KEYCLOAK_CLIENT_IDService Account client IDrequired
KEYCLOAK_CLIENT_SECRETClient secretrequired
KEYCLOAK_SITES_INIINI file for IP-to-site labeling (see below)unset
KEYCLOAK_KNOWN_EGRESSComma-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 excludedunset
KEYCLOAK_DEFAULT_DATE_FROM_HOURSDefault 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_DEADLINEPer-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_EVENTSPer-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_USERSDefault 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_WHITELISTComma-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_ROOTEnables 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_MAXMaximum rows per group-change call.30
KEYCLOAK_GROUP_MODEmulti (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_DIRDirectory 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_DEADLINETime 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_SESSION_PROBESSeparate connections whose session listings get_user_sessions (and the remaining-session count of set_user_enabled) merges. Behind a load balancer, KeyCloak nodes that do not share user sessions (no distributed Infinispan cache) each list only their own.8
KEYCLOAK_LOGOUT_CLEAN_PROBESlogout_user keeps probing — each probe on its own connection lists the sessions and logs the user out on the node it reached when that node lists a session — until this many probes in a row see no session. The first probe sends the logout even when it lists nothing: it also sets the user's notBefore in the database, which all nodes check, and the tool reports it. Which node a new connection reaches is up to the load balancer: under source-IP affinity the probes may never reach some node, so notBefore is the effect that holds on every node. Where sessions are shared, set this and KEYCLOAK_SESSION_PROBES to 1.10
KEYCLOAK_LOGOUT_MAX_PROBESUpper bound on logout_user probes; if sessions are still seen at the bound, the tool says so (⚠️) instead of reporting success. The probes, like the session listings of get_user_sessions and set_user_enabled, are bounded by KEYCLOAK_DEADLINE; when it runs out or a request fails, the tool says verification is incomplete (⚠️) and reports what was done so far.40

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.

ToolAdmin API call
reset_passwordPUT /users/{id}/reset-password
reset_passwords_batchthe same call, once per CSV row
set_user_enabledPUT /users/{id} with enabled toggled
logout_userGET /users/{id}/sessions + POST /users/{id}/logout, repeated on new connections (see KEYCLOAK_LOGOUT_CLEAN_PROBES)

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 an AI assistant 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.

ToolAdmin API call
plan_group_changesread-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_changesPUT /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:

bash
export KEYCLOAK_URL=https://keycloak.example.comexport KEYCLOAK_REALM=my-realmexport KEYCLOAK_CLIENT_ID=keycloak-mcpexport KEYCLOAK_CLIENT_SECRET=your-secretkeycloak-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:

ini
[hq]name = HQ (Tokyo)ipv4 = 192.0.2.0/24, 198.51.100.0/24ipv6 = 2001:db8:1::/48
[vpn]name = VPNipv4 = 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:

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:

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": ""      }    }  }}

Codex

bash
codex mcp add keycloak-mcp \  --env KEYCLOAK_URL=https://keycloak.example.com \  --env KEYCLOAK_REALM=my-realm \  --env KEYCLOAK_CLIENT_ID=keycloak-mcp \  --env KEYCLOAK_CLIENT_SECRET=your-secret \  -- keycloak-mcp

Any other MCP client that launches stdio servers works the same way: give it keycloak-mcp as the command and set the KEYCLOAK_* variables in its environment.

From a shell

bash
export KEYCLOAK_URL=https://keycloak.example.comexport KEYCLOAK_REALM=my-realmexport KEYCLOAK_CLIENT_ID=keycloak-mcpexport KEYCLOAK_CLIENT_SECRET=your-secretkeycloak-mcp

CLI

bash
keycloak-mcp --version   # Print version and exitkeycloak-mcp --help      # Show usage and required environment variableskeycloak-mcp --check     # Verify env vars and authentication, then exitkeycloak-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:

bash
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

bash
git clone https://github.com/shigechika/keycloak-mcp.gitcd keycloak-mcp
# uvuv sync --devuv run pytest -vuv run ruff check .
# pippython3 -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:

bash
# needs KEYCLOAK_URL / KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRETuv run python scripts/smoke_test.pyuv 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

來源：README.md，提交 36b7355

工具

33

health_check

Report server version and KeyCloak backend connectivity / authentication. Call this at session start (or after a tool-call timeout) to confirm the MCP is up, see which version is running, and verify the KeyCloak Admin API is reachable and the service account can authenticate. Lightweight: it acquires an admin access token via the Client Credentials Grant (reusing the cached client) and does NOT enumerate users, events, or sessions. Always returns the same keys: ``status`` (healthy / degraded / error), ``service``, ``version``, ``keycloak_url`` (configured base URL, empty if unset), ``realm`` (configured realm), ``keycloak_version`` (None — not exposed by a cheap call), and ``auth`` (ok / error / missing-env). On a degraded or error result, ``detail`` carries the reason. This description is the only place those value sets are written down. The READMEs used to repeat them, which is three copies to keep in step and two that an LLM never reads — it is handed this text.

無需輸入參數。

count_users

Get total user count in the realm.

無需輸入參數。

search_users

Search users by username, email, first name, or last name. Args: query: Search string (partial match). max_results: Maximum results to return (default 20).

輸入參數query必填max_results

get_user

Get detailed user information by exact username (email). If KEYCLOAK_USER_ATTRIBUTE_WHITELIST names any custom attribute keys, this also does one extra by-ID lookup and appends whichever of those keys are present on the user (the search endpoint used to resolve the username returns a brief representation that omits ``attributes`` entirely). A whitelisted key whose name looks credential-shaped (contains "password", "secret", "token", etc. — see _looks_like_credential_key) is reported as blocked rather than shown, as a safety net on top of the whitelist itself. Args: username: Exact username (e.g., [email protected]).

輸入參數username必填

reset_password

Reset a user's password. Args: username: Exact username (email). password: New password to set. temporary: If True, user must change password on next login.

輸入參數password必填username必填temporary

reset_passwords_batch

Reset passwords for multiple users from CSV text. Each line should be: username,password If password column is empty, a random 12-char password is generated and included in the response (the caller cannot recover it otherwise). Caller-supplied passwords are never echoed back. Args: csv_text: CSV text with username,password per line (header optional). temporary: If True, users must change password on next login.

輸入參數csv_text必填temporary

get_user_sessions

Get active sessions for a user. Sessions are listed over several separate connections and merged, because behind a load balancer a KeyCloak node that does not share sessions with the others lists only its own (KEYCLOAK_SESSION_PROBES, default 8). Args: username: Exact username (email).

輸入參數username必填

logout_user

Force logout a user by removing all their active sessions. Each probe opens its own connection, lists the user's sessions and logs the user out on the node it reached when that node lists a session. Until one logout has gone through it is sent even when the node lists nothing: it also sets the user's ``notBefore`` in the database, so tokens issued before it are rejected by every node. Probing goes on until no session is seen on KEYCLOAK_LOGOUT_CLEAN_PROBES probes in a row (default 10), at most KEYCLOAK_LOGOUT_MAX_PROBES (default 40), so that nodes that do not share sessions behind a load balancer are all reached. The resulting ``notBefore`` is reported. The whole run is bounded by KEYCLOAK_DEADLINE; when it runs out or a request fails, the result says verification is incomplete, with what was done so far. Args: username: Exact username (email).

輸入參數username必填

set_user_enabled

Enable or disable a user account. Disabling blocks all authentication (SSO logins) for the user — the containment action for a compromised or decommissioned account. Only the ``enabled`` flag is changed; custom attributes are preserved. Disabling does not terminate existing sessions (an already-issued token stays valid until it expires), so when disabling this reports how many sessions remain and to run ``logout_user`` to end them immediately. Args: username: Exact username (email). enabled: True to enable, False to disable.

輸入參數enabled必填username必填

get_user_credentials

List the credential types configured for one user (password, otp, webauthn, …). Use this to check a single user's MFA status: an ``otp`` credential means TOTP/HOTP is configured. Reads ``/users/{id}/credentials`` (read-only; does not create a session). Args: username: Exact username (email).

輸入參數username必填

get_totp_users

Report how many users have TOTP (OTP) configured across the realm. Enumerates users and inspects each one's credentials for an ``otp`` entry. KeyCloak has no bulk credential endpoint, so this makes one credential request per user (N+1) — expect it to be slow on large realms; bound it with ``max_users`` (which also short-circuits the user enumeration). Users whose credential lookup fails are counted separately and skipped, so a single transient error does not abort the whole scan. Args: enabled_only: Only scan enabled users (default True). list_users: Include the list of usernames with TOTP (default True). max_users: Cap the number of users scanned. ``0`` (default) falls back to KEYCLOAK_MAX_USERS (default 5000) rather than the whole realm. The N+1 credential loop is also bounded by KEYCLOAK_DEADLINE, so a large realm returns a disclosed sample. When capped, the percentage covers only the sample, not the realm.

輸入參數max_userslist_usersenabled_only

get_brute_force_status

Check if a user is temporarily locked due to brute force detection. Args: username: Exact username (email).

輸入參數username必填

list_user_groups

List groups a user belongs to. Args: username: Exact username (email).

輸入參數username必填

list_users_by_group

List all users in a group. Args: group_name: Group name (partial match). max_results: Maximum results (default 100).

輸入參數group_name必填max_results

get_events

Get KeyCloak events with optional filters. Args: event_type: Event type filter (e.g., LOGIN, LOGIN_ERROR, UPDATE_PASSWORD). username: Filter by exact username (email). Resolved to user ID internally. client_id: Filter by client ID (SP name). ip_address: Filter events by source IP (client-side filter). date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). max_results: Maximum results (default 50).

輸入參數date_tousernameclient_iddate_fromevent_typeip_addressmax_results

get_login_stats

Get login success/failure statistics with full pagination. Time-bounded: this call stops after KEYCLOAK_DEADLINE seconds (default 45) and returns what it has; the counts are then a lower bound. The result then starts with a "PARTIAL RESULT" warning. Call again with a narrower window instead of retrying the same call. A wide window on a busy day is what triggers it. Args: date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). Empty for all.

輸入參數date_todate_from

get_login_stats_by_hour

Get login statistics broken down by hour (local time). Time-bounded: this call stops after KEYCLOAK_DEADLINE seconds (default 45) and returns what it has; the counts are then a lower bound. The result then starts with a "PARTIAL RESULT" warning. Call again with a narrower window instead of retrying the same call. A wide window on a busy day is what triggers it. Args: date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). Empty for all.

輸入參數date_todate_from

get_login_failures_by_ip

Get login failure statistics broken down by source IP. Time-bounded: this call stops after KEYCLOAK_DEADLINE seconds (default 45) and returns what it has; the counts are then a lower bound. The result then starts with a "PARTIAL RESULT" warning. Call again with a narrower window instead of retrying the same call. A wide window on a busy day is what triggers it. Args: date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). Empty for all. top: Number of top IPs to show (default 20).

輸入參數topdate_todate_from

get_ip_activity

Exhaustive investigation of all activity from one source IP address. Unlike `get_events(ip_address=...)`, which filters a single page and can miss activity outside the most recent `max_results` events, this tool fully paginates every requested event type (via `get_events_all`) before filtering by IP, so the result is exhaustive over the requested date range. Use this for brute-force / credential-stuffing / shared-workstation investigations where `get_login_failures_by_ip` told you *which* IP to look at and you now need the full picture for that one IP. Returns a fixed-shape dict (JSON), not formatted text — every key below is always present, even when zero events match. Returns: error: None on success. Set to a descriptive message if event_types resolved to no event types (e.g. empty or all-whitespace/commas); every other key is still present, with an empty/zero result in that case (no data was fetched). ip_address: Echoes the input. site: Site name from KEYCLOAK_SITES_INI, or null if unmatched or unconfigured (see sites_configured to tell those apart). sites_configured: True if KEYCLOAK_SITES_INI was loaded at all. date_from / date_to: The resolved date range actually scanned. event_types: The event types scanned (echoes the input, split). summary: total_events, login_success, login_failure, unique_users, unique_clients, first_seen/last_seen (ISO 8601, null if no match). login_success/login_failure classify EVERY scanned event type by whether its type ends in "_ERROR" (matching the users/clients breakdown below), not just literal LOGIN/LOGIN_ERROR — so widening event_types always keeps these numbers reconciled with the per-user/per-client totals. Always computed over the FULL matched set, unaffected by max_timeline truncation. use

輸入參數date_todate_fromip_address必填event_typesmax_timeline

spray_check

Detect password-spray sources and name the accounts they breached — one rule, one call. For every EXTERNAL source IP (anything outside the ranges declared in KEYCLOAK_SITES_INI) seen in LOGIN / LOGIN_ERROR events during the last ``hours``, compute distinct users and success rate. An IP is a spray source when ``unique_users >= min_users`` AND ``success_rate < max_success_rate``. Its successful logins are the breach CANDIDATES; whether they may be called breached depends on the row's ``confidence``. The breach list is built ONLY from LOGIN events whose source IP is the flagged IP, inside the window. Every entry carries the evidence tuple ``{time, ip, username, user_id, client_id}``. A compromised account can therefore never be reported without an actual login event from the spray source — do not add names that are not in ``spray[].breached``. ``confidence`` separates a spray from a shared egress (school NAT, home line, VDI) that merely looks like one by volume. It is "low" — treat the successes as "verify with the owner", never publish them as breached — when any of these ``signals`` holds: ``user_success_rate`` (distinct users that logged in at least once ÷ distinct users) >= ``max_user_success_rate`` (real sprays sit at 0.0–0.06; a school NAT with students retyping a mistyped domain sat at 0.47), or ``failure_concentration`` (share of failures on the single most-failing username) >= ``max_failure_concentration`` (one locked-out user retrying from a shared line produced 0.91), or the IP is in KEYCLOAK_KNOWN_EGRESS. Only ``confidence: high`` rows are a breach verdict. Read ``top_failed_users`` and ``not_found_domains`` (domains of usernames that do not exist — typos of the real domain are humans, not a scraped list) before writing anything up. Returns a fixed-shape dict: window: {hours, since, until} actually scanned. complete: False if event pag

輸入參數hoursmin_usersmax_resolvesmax_success_ratemin_report_usersmax_user_success_ratemax_failure_concentration

get_login_stats_by_client

Get login statistics broken down by client (SP). Time-bounded: this call stops after KEYCLOAK_DEADLINE seconds (default 45) and returns what it has; the counts are then a lower bound. The result then starts with a "PARTIAL RESULT" warning. Call again with a narrower window instead of retrying the same call. A wide window on a busy day is what triggers it. Args: date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). Empty for all.

輸入參數date_todate_from

detect_login_loops

Detect users with rapid repeated logins (possible redirect loops). Scans all LOGIN events and finds users who logged in more than `threshold` times within `window_seconds`. Time-bounded: this call stops after KEYCLOAK_DEADLINE seconds (default 45) and returns what it has; the counts are then a lower bound. The result then starts with a "PARTIAL RESULT" warning. Call again with a narrower window instead of retrying the same call. A wide window on a busy day is what triggers it. Args: date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). Empty for all. threshold: Minimum logins within the window to flag (default 10). window_seconds: Time window in seconds (default 60). top: Number of top users to show (default 20). Use 0 for all.

輸入參數topdate_todate_fromthresholdwindow_seconds

get_password_update_events

Get password update events. Args: date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). max_results: Maximum results (default 100).

輸入參數date_todate_frommax_results

get_admin_events

Get KeyCloak admin events (changes performed via the Admin REST API). Admin events record operations performed by service accounts or admin users — e.g. custom user attribute updates (``provisioning_flag``), role / group assignments, client configuration changes. These are distinct from user events (login / password change). Use this when ``UPDATE_PROFILE`` in ``get_events`` is empty but an attribute is known to have changed. Args: operation_types: Comma-separated list of CREATE, UPDATE, DELETE, ACTION. resource_types: Comma-separated list of USER, CLIENT, ROLE, GROUP, REALM_ROLE, etc. resource_path: Filter by resource path (e.g. "users/{userId}"). date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). max_results: Maximum results (default 50). max_repr: Max chars of the representation field. 0 = omit, -1 = full.

輸入參數date_tomax_reprdate_frommax_resultsresource_pathresource_typesoperation_types

get_user_attribute_history

Get admin-side attribute change history for a single user. Queries admin events scoped to ``users/{userId}`` with UPDATE / ACTION operations. Intended for tracking custom attribute changes such as ``provisioning_flag`` which are written by admin API and do **not** surface in ``get_events`` (which only shows user-driven events like LOGIN / UPDATE_PASSWORD). Args: username: Exact username (email). date_from: Start date (YYYY-MM-DD). Defaults to last 24h when omitted (KEYCLOAK_DEFAULT_DATE_FROM_HOURS). date_to: End date (YYYY-MM-DD). max_results: Maximum results (default 100). max_repr: Max chars of the representation field. 0 = omit, -1 = full.

輸入參數date_tomax_reprusername必填date_frommax_results

get_session_stats

Get active session count per client.

無需輸入參數。

get_client_sessions

Get active sessions for a specific client (SP). Args: client_id: Client ID (e.g., 'xflow', 'shadowserver'). max_results: Maximum results (default 100).

輸入參數client_id必填max_results

list_clients

List all SAML/OIDC clients in the realm.

無需輸入參數。

get_client

Show one client's configuration, including its authentication flow overrides. Reports an explicit allowlist of fields rather than the raw client representation. A client representation can carry ``secret``, ``registrationAccessToken`` and, for SAML clients, signing material under ``attributes``; ``attributes`` and ``protocolMappers`` are therefore omitted entirely rather than filtered, so nothing credential-shaped reaches tool output, hence LLM context. The headline is ``authenticationFlowBindingOverrides``: pinning one client to a non-default browser flow is how a single SP is made to require OTP while the realm default stays untouched. KeyCloak stores those overrides as flow IDs, so they are resolved to flow aliases here. Args: client_id: The clientId (not the internal UUID).

輸入參數client_id必填

get_realm_roles

List all realm-level roles.

無需輸入參數。

get_realm_security_defenses

Show the realm's security-defense settings (read-only). Reports the realm-level security configuration that the admin console groups under "Security defenses": - Brute force detection: whether it is enabled, the lockout strategy, and the thresholds (max login failures, wait increments, reset window). - Password policy. - Browser security headers. Use this to verify that brute-force protection is actually turned on and how aggressively it locks accounts — the per-user ``get_brute_force_status`` only reflects runtime state, not whether the policy itself is configured.

無需輸入參數。

get_config_changes

Compare the realm configuration now with a stored daily snapshot (read-only). Covers realm settings (brute force detection, password and OTP policies, session and token lifespans, flow bindings), event settings, realm roles and the contents of composite roles, authentication flows and their executions, required actions, clients (redirect URIs, flows allowed, flow overrides, protocol mappers), client scopes, default client scopes, components and, when readable, identity providers. Values under credential-named keys (``secret``, ``password``, ``privateKey``, ``apiKey``, ...) are replaced with ``<redacted>`` before anything is compared or stored, so a changed secret does not show as a change. The snapshots are written by ``daily_brief`` (the first run of each day); this tool never writes one. Use it to see the full list when ``daily_brief`` reports [CONFIG] changes, or to compare against an older day. Args: baseline_date: Snapshot to compare against (YYYY-MM-DD). Default: the latest snapshot before today.

輸入參數baseline_date

daily_brief

Run a morning Keycloak health check. Checks (all scoped to the last ``since_hours`` hours): - Login statistics (success / failure totals, top failing IPs) - Active sessions by client - Password update events - Admin events (CREATE/UPDATE/DELETE on USER/CLIENT resources) - Configuration: admin events that change roles, role mappings, flows, client scopes, protocol mappers, components or the realm, and (when KEYCLOAK_STATE_DIR is set) what changed since the last daily snapshot. The first run of each day records that day's snapshot; ``get_config_changes`` lists every change. A single IP with login failures >= ``ip_failure_threshold`` is flagged as WARNING (possible brute-force). Independently, the same login events are run through the ``spray_check`` rule (external IP, >= 10 distinct users, success rate < 20%); a match is a [SPRAY] WARNING and the "Spray check" section lists the breached accounts with their evidence tuples (time / ip / username / client). Only accounts in that list may be called breached — see ``spray_check`` for the full row shape and to widen the window or tune the thresholds. ``since_hours`` defaults to 18 (≈ previous 15:00 for a 09:00 morning run). Output tiers: - CRITICAL — API connection failure - WARNING — anomalies detected - OK — clean Args: since_hours: Look-back window in hours (default 18). ip_failure_threshold: Login failures from a single IP that triggers a WARNING (default 50).

輸入參數since_hoursip_failure_threshold

版本歷史

9
  1. v1.5.1最新Oct 22, 2026
  2. v1.5.0Oct 11, 2026
  3. v1.4.0Oct 11, 2026
  4. v1.2.0Oct 9, 2026
  5. v1.0.1Sep 29, 2026
  6. v0.21.0Sep 23, 2026
  7. v0.20.0Sep 20, 2026
  8. v0.19.0Sep 18, 2026
  9. v0.18.0Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分