MCP server for KeyCloak Admin REST API via Service Account
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent β or use 1-click editor setup below.
Not yet automatically verified
We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag β we're steadily working through the catalog.
Manual Client & Custom JSON ConfigExpand JSON βΎ
Client Config & Setup
Choose your client or environment
Target File:
π‘ Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Documentation Overview
keycloak-mcp
English | ζ₯ζ¬θͺ
An MCP (Model Context Protocol) server for the KeyCloak Admin REST API.
Documentation: https://shigechika.github.io/keycloak-mcp/
Authenticates via a Service Account (Client Credentials Grant), so no human password or TOTP is involved. Also Infinispan-safe β it never creates user sessions and never hits the userinfo endpoint.
Features
Users
| Tool | Description |
|---|---|
count_users | Total user count in the realm |
search_users | Partial-match search (username / email / name) |
get_user | Full detail for an exact username |
reset_password | Reset one user's password |
reset_passwords_batch | Bulk reset from CSV (username,password per line; blank password is generated) |
get_user_sessions | Active sessions for one user, timestamps in local time |
logout_user | Kill all active sessions for one user |
set_user_enabled | Enable or disable one user; disabling blocks all logins (custom attributes preserved) |
MFA / Credentials
| Tool | Description |
|---|---|
get_user_credentials | Credential types configured for one user; an otp entry means TOTP/HOTP is set up |
get_totp_users | Realm-wide TOTP adoption: how many users have an otp credential, with percentage and (optionally) the user list. Enumerates users and reads each one's credentials (N+1; bound with max_users) |
Groups
| Tool | Description |
|---|---|
list_user_groups | Which groups a user belongs to |
list_users_by_group | Members of a group |
Security
| Tool | Description |
|---|---|
get_brute_force_status | Whether a user is currently locked by brute-force detection |
get_realm_security_defenses | Realm-level security policy: whether brute-force detection is enabled and its thresholds, the password policy, and browser security headers |
get_login_failures_by_ip | Failure breakdown by source IP (site-labeled when KEYCLOAK_SITES_INI is set) |
get_ip_activity | Exhaustive investigation of one source IP: success/failure counts, affected users/clients, timeline. Returns structured JSON. |
detect_login_loops | Flag users who logged in too many times in a short window (redirect loops) |
Events
| Tool | Description |
|---|---|
get_events | Filter by type, username, client, IP, and date range. Username is resolved to user ID internally. Failure events include KeyCloak's error field (e.g. invalid_user_credentials). |
get_login_stats | Login success/failure totals, paginated across all results |
get_login_stats_by_hour | Logins bucketed by hour of day (local time) |
get_login_stats_by_client | Logins bucketed by client / SP |
get_password_update_events | UPDATE_PASSWORD history |
Admin Events
get_events only sees user events. Actions driven by an admin β or by a service account writing custom attributes β don't show up there. The admin-event endpoint fills that gap.
| Tool | Description |
|---|---|
get_admin_events | Filter by operation (CREATE / UPDATE / DELETE / ACTION), resource type (USER / CLIENT / ROLE / GROUP / β¦), resource path, and date range |
get_user_attribute_history | UPDATE/ACTION events scoped to one user β handy for tracking when a custom attribute (e.g. provisioning_flag) was written by an automated pipeline |
Both tools accept max_repr to control the representation payload: positive = truncate to N chars (default 500), 0 = omit, negative = include in full.
Sessions & Clients
| Tool | Description |
|---|---|
get_session_stats | Active session count per client |
get_client_sessions | Active sessions for one client (SP) |
list_clients | SAML and OIDC clients in the realm |
get_realm_roles | Realm-level roles |
Morning Patrol
| Tool | Description |
|---|---|
health_check | Report the running server version and verify the KeyCloak backend is reachable and the service account can authenticate. Lightweight (one token request; no user/event/session scans). Returns a fixed-shape dict with status, auth, and the configured URL/realm. The tool's own description enumerates the values those fields can take, and is the one place that does. |
daily_brief | One-shot morning health check: login stats, brute-force IPs, active sessions, password updates, and admin events in a single Markdown summary. IPs exceeding ip_failure_threshold failures (default 50) are flagged WARNING; API errors surface as CRITICAL. since_hours controls the look-back window (default 18 h). |
Setup
From source:
Configuration
| Variable | Description | Default |
|---|---|---|
KEYCLOAK_URL | Base URL, e.g. https://keycloak.example.com | required |
KEYCLOAK_REALM | Realm name | master |
KEYCLOAK_CLIENT_ID | Service Account client ID | required |
KEYCLOAK_CLIENT_SECRET | Client secret | required |
KEYCLOAK_SITES_INI | INI file for IP-to-site labeling (see below) | unset |
KEYCLOAK_DEFAULT_DATE_FROM_HOURS | Default look-back window for event tools when date_from is omitted. Set to 0 to scan full history (can hang on large realms). | 24 |
KEYCLOAK_DEADLINE | Per-call wall-clock budget (seconds) for the heavy event/TOTP tools. When a wide window / large realm would exceed it, the tool stops and returns a disclosed partial (β οΈ warning) instead of running past the client's ~60s gateway timeout and hammering KeyCloak. 0 or negative disables. | 45 |
KEYCLOAK_MAX_EVENTS | Per-pagination cap on events fetched by the event tools (also bounds how deep the slow high-offset pagination goes). Over the cap the result is a disclosed partial. 0 or negative disables. | 200000 |
KEYCLOAK_MAX_USERS | Default cap on users scanned by get_totp_users when its max_users argument is 0 (each user costs one credential call). 0 or negative disables (whole realm, bounded only by KEYCLOAK_DEADLINE). | 5000 |
KEYCLOAK_USER_ATTRIBUTE_WHITELIST | Comma-separated custom user-attribute keys that get_user is allowed to surface. Unset by default: get_user only ever returns username/name/email/enabled/created, since the search endpoint it resolves the username through returns a brief representation with no attributes at all. Opting a key in makes get_user do one extra by-ID lookup and append that attribute's value when present. Everything else stays out of tool output. As a safety net, a whitelisted key whose name looks credential-shaped (contains password, secret, token, etc.) is reported as blocked rather than shown β not a guarantee, since a credential attribute named outside that pattern list still gets through. | unset |
KeyCloak client setup
- Create a new client in the KeyCloak admin console.
- Turn on Client authentication and Service account roles.
- Give it
view-users,view-events,view-clients, and β only if you need password reset βmanage-users.
Write operations
Four tools change state. Everything else only reads.
| Tool | Admin API call |
|---|---|
reset_password | PUT /users/{id}/reset-password |
reset_passwords_batch | the same call, once per CSV row |
set_user_enabled | PUT /users/{id} with enabled toggled |
logout_user | POST /users/{id}/logout |
All four need manage-users on the Service Account. Leave that role off and the
server is read-only: those four tools fail with 403 and every other tool keeps
working, so a realm can be handed to Claude for investigation without granting any
ability to modify it. Grant manage-users only when account recovery or
containment is part of the job.
Verify your setup
After setting the environment variables, run --check to confirm authentication works before wiring it into an MCP client:
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:
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:
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.
Related MCP Servers
Reviews
No reviews yet β be the first to share how this listing worked for you.
Frequently Asked Questions about KeyCloak MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/keycloak-mcp)HTML Embed
<a href="https://allmcps.com/mcp/keycloak-mcp"><img src="https://allmcps.com/api/badge/keycloak-mcp?style=directory" alt="KeyCloak MCP on AllMCPs" /></a>Technical Specs & Signals
CategoryDeveloper Tools
35Quality signal: Fair Β· 35/100How this signal is calculated βΎ
Server availabilityNot measured
Not scored for repo-hosted servers β we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.
Verified ownership10/20
Documentation & tools15/30
Adoption & activity1/15
Community engagement0/10
A guidance signal from public completeness & health data β not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.
Own this project?
This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge β proof is checked automatically, then reviewed by our team.
Free dofollow backlink: add your website and place the AllMCPs badge on it β no claim needed. We detect it automatically and keep it verified as long as the badge stays live.
Claim & get free dofollowShare & Embed
Add our SVG badge (dark/light directory styles) or embeddable widget to your site.