Skip to content
Agentmart
Submit a tool

KeyCloak MCP

MCP server for KeyCloak Admin REST API via Service Account

Connector by shigechika · GitHub account verified by the MCP Registry

IndexedMITLocal (stdio)
Write a review

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/shigechika-keycloak-mcp

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

We use your email only for this newsletter. Privacy

About

MCP server for KeyCloak Admin REST API via Service Account

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 26, 2026.

Tools
29 read · 3 write · 3 delete
Secrets
None asked for
Install scripts
None found
Runs as
Python package

Tools by what they do 35

Read from the source code; the running server may list different tools.

Read 29 · Look things up without changing anything.

  • count_users
  • detect_login_loops
  • get_admin_events
  • get_brute_force_status
  • get_client
  • get_client_sessions
  • get_config_changes
  • get_events
  • get_ip_activity
  • get_login_failures_by_ip
  • get_login_stats
  • get_login_stats_by_client
Show 17 more tools
  • get_login_stats_by_hour
  • get_password_update_events
  • get_realm_roles
  • get_realm_security_defenses
  • get_session_stats
  • get_totp_users
  • get_user
  • get_user_attribute_history
  • get_user_credentials
  • get_user_sessions
  • health_check
  • list_clients
  • list_user_groups
  • list_users_by_group
  • plan_group_changes
  • search_users
  • spray_check

Write 3 · Create, change, send or run things.

  • apply_group_changes
  • daily_brief
  • set_user_enabled

Delete 3 · Delete, drop, revoke or wipe things.

  • logout_user
  • reset_password
  • reset_passwords_batch

Network hosts it talks to 4

  • github.com · found in code
  • json.schemastore.org · found in code
  • raw.githubusercontent.com · found in code
  • shigechika.github.io · found in code

Tools (35)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

  • apply_group_changes

    Apply a batch of group moves that a human approved from plan_group_changes. Writes. Call it only after a person has seen the plan and approved it: the digest is a check that nothing changed since the plan, not proof of approval, and this server cannot tell the two apart. Treat an approval as single-use: if the memberships return to the planned state (for example after ``reverse``), the old digest matches again. Re-plans first and changes nothing unless every row is still executable and the fresh digest equals ``expected_digest`` (any membership change since the plan, by anyone, aborts the who…

  • count_users

    Get total user count in the realm.

  • 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 w…

  • 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).…

  • 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, et…

  • get_brute_force_status

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

  • 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 requi…

  • 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).

  • 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 `…

  • 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).

  • 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 …

  • 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).

  • 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.

  • 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.

  • 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.

Show 20 more tools
  • 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).

  • 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_session_stats

    Get active session count per client.

  • 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 wit…

  • 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 userna…

  • 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). …

  • 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).

  • 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).

  • 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``…

  • list_clients

    List all SAML/OIDC clients in the realm.

  • list_user_groups

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

  • list_users_by_group

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

  • 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 bala…

  • plan_group_changes

    Check a batch of group moves without changing anything (e.g. staff transfers). Read-only. Use this first and show the result to a human. Only after they approve it, call apply_group_changes with the same changes and this result's ``digest``. Args: changes: List of objects ``{"username": "<exact username>", "remove": "<full group path or null>", "add": "<full group path or null>"}``. Paths are exact and absolute (e.g. ``/Staff/Faculty/Office/Section``); partial names are not matched. When the server is configured for one group per user, ``add`` is required and an …

  • 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.

  • 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.

  • 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).

  • 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.

  • 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 w…

Signals

Stars
0
Forks
0
Open issues
8
Weekly downloads
286
Last commit
Oct 22, 2026 (6 days ago)
Last release
Oct 22, 2026 (6 days ago)
Last package publish
Oct 22, 2026 (6 days ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name
io.github.shigechika/keycloak-mcp
Version
1.5.1
Auth
No auth
Packages
pypi keycloak-mcp
License
MIT
Repository
github.com/shigechika/keycloak-mcp
First seen
Oct 24, 2026
Last checked
Oct 24, 2026
Source
Official MCP Registrygithub-graphql

More from shigechika

Cite this page

KeyCloak MCP. Agent Mart. https://agentmart.dev/connectors/shigechika-keycloak-mcp (last updated 2026-10-24)