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 分