shigechika / MCP Servers · Registry oficial
keycloak-mcp
MCP server for the Keycloak Admin REST API — a strong ally for auth troubleshooting: inspect users, sessions, clients, and realm config through AI assistants.
- 0 estrellas
- 0 forks
- 8 issues abiertos
- Lenguaje: Python
- Licencia: MIT
- actualizado
Instalación
local · pip / pythonClaude Code CLI
claude mcp add keycloak-mcp -- python -m keycloak-mcpclaude_desktop_config.json
{
"mcpServers": {
"keycloak-mcp": {
"command": "python",
"args": ["-m", "keycloak-mcp"]
}
}
}~/.cursor/mcp.json
{
"mcpServers": {
"keycloak-mcp": {
"command": "python",
"args": ["-m", "keycloak-mcp"]
}
}
}- Run the command above in your terminal (Claude Code), or paste the JSON config into claude_desktop_config.json (Claude Desktop).
- Replace any <placeholder> values with your API keys or paths.
- Restart Claude. The MCP server and its tools appear automatically.
Install first: pip install keycloak-mcp
README
Resumen de MCP Servers
keycloak-mcp
English | 日本語
An MCP (Model Context Protocol) server for the KeyCloak Admin REST API.
Documentation: https://shigechika.github.io/keycloak-mcp/
Authenticates via a Service Account (Client Credentials Grant), so no human password or TOTP is involved. Also Infinispan-safe — it never creates user sessions and never hits the userinfo endpoint.
Features
Users
| Tool | Description |
|---|---|
count_users | Total user count in the realm |
search_users | Partial-match search (username / email / name) |
get_user | Full detail for an exact username |
reset_password | Reset one user's password |
reset_passwords_batch | Bulk reset from CSV (username,password per line; blank password is generated) |
get_user_sessions | Active sessions for one user, timestamps in local time |
logout_user | Kill all active sessions for one user |
set_user_enabled | Enable or disable one user; disabling blocks all logins (custom attributes preserved) |
MFA / Credentials
| Tool | Description |
|---|---|
get_user_credentials | Credential types configured for one user; an otp entry means TOTP/HOTP is set up |
get_totp_users | Realm-wide TOTP adoption: how many users have an otp credential, with percentage and (optionally) the user list. Enumerates users and reads each one's credentials (N+1; bound with max_users) |
Groups
| Tool | Description |
|---|---|
list_user_groups | Which groups a user belongs to |
list_users_by_group | Members of a group |
Security
| Tool | Description |
|---|---|
get_brute_force_status | Whether a user is currently locked by brute-force detection |
get_realm_security_defenses | Realm-level security policy: whether brute-force detection is enabled and its thresholds, the password policy, and browser security headers |
get_config_changes | What changed in the realm configuration since a stored daily snapshot (see Configuration snapshots). Read-only; baseline_date picks an older snapshot. |
get_login_failures_by_ip | Failure breakdown by source IP (site-labeled when KEYCLOAK_SITES_INI is set) |
get_ip_activity | Exhaustive investigation of one source IP: success/failure counts, affected users/clients, timeline. Returns structured JSON. |
spray_check | Password-spray detection with the breach list built in: every external IP with ≥ 10 distinct users and < 20 % login success is a spray source, and its successful logins (evidence tuple time / ip / username / user_id / client_id) are the breach candidates. Each row carries a confidence: high is a breach verdict; low means the volume rule fired on a shared egress (school NAT, home line, VDI) — signalled by user_success_rate (distinct users that logged in ÷ distinct users, ≥ 0.2), failure_concentration (share of failures on one username, ≥ 0.5) or a KEYCLOAK_KNOWN_EGRESS match — and the logins are to be verified with the owner, not published. top_failed_users and not_found_domains show who kept failing and which mistyped domains produced user_not_found. Fixed-shape JSON, complete: false when the window was truncated. |
detect_login_loops | Flag users who logged in too many times in a short window (redirect loops) |
Events
| Tool | Description |
|---|---|
get_events | Filter by type, username, client, IP, and date range. Username is resolved to user ID internally. Failure events include KeyCloak's error field (e.g. invalid_user_credentials). |
get_login_stats | Login success/failure totals, paginated across all results |
get_login_stats_by_hour | Logins bucketed by hour of day (local time) |
get_login_stats_by_client | Logins bucketed by client / SP |
get_password_update_events | UPDATE_PASSWORD history |
Admin Events
get_events only sees user events. Actions driven by an admin — or by a service account writing custom attributes — don't show up there. The admin-event endpoint fills that gap.
| Tool | Description |
|---|---|
get_admin_events | Filter by operation (CREATE / UPDATE / DELETE / ACTION), resource type (USER / CLIENT / ROLE / GROUP / …), resource path, and date range |
get_user_attribute_history | UPDATE/ACTION events scoped to one user — handy for tracking when a custom attribute (e.g. provisioning_flag) was written by an automated pipeline |
Both tools accept max_repr to control the representation payload: positive = truncate to N chars (default 500), 0 = omit, negative = include in full.
Sessions & Clients
| Tool | Description |
|---|---|
get_session_stats | Active session count per client |
get_client_sessions | Active sessions for one client (SP) |
list_clients | SAML and OIDC clients in the realm |
get_client | One client's configuration, including its authentication flow overrides (the per-SP MFA switch). Omits attributes and protocolMappers, so no client secret or SAML signing material reaches tool output. |
get_realm_roles | Realm-level roles |
Morning Patrol
| Tool | Description |
|---|---|
health_check | Report the running server version and verify the KeyCloak backend is reachable and the service account can authenticate. Lightweight (one token request; no user/event/session scans). Returns a fixed-shape dict with status, auth, and the configured URL/realm. The tool's own description enumerates the values those fields can take, and is the one place that does. |
daily_brief | One-shot morning health check: login stats, brute-force IPs, spray check (same rule as spray_check, with breached accounts and evidence), active sessions, password updates, admin events, and configuration changes (admin events on roles, role mappings, flows, client scopes, protocol mappers, components and the realm, plus the snapshot comparison when KEYCLOAK_STATE_DIR is set; both are flagged [CONFIG]), and additions to groups that carry roles (flagged [PRIVILEGE] when the group grants a realm-management role other than the read-only query-*/view-*) in a single Markdown summary. IPs exceeding ip_failure_threshold failures (default 50) and spray sources are flagged WARNING; API errors surface as CRITICAL. since_hours controls the look-back window (default 18 h). |
Setup
# uv
uv pip install keycloak-mcp
# pip
pip install keycloak-mcpFrom source:
git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp
# uv
uv sync
# pip
pip install -e .Configuration
| Variable | Description | Default |
|---|---|---|
KEYCLOAK_URL | Base URL, e.g. https://keycloak.example.com | required |
KEYCLOAK_REALM | Realm name | master |
KEYCLOAK_CLIENT_ID | Service Account client ID | required |
KEYCLOAK_CLIENT_SECRET | Client secret | required |
KEYCLOAK_SITES_INI | INI file for IP-to-site labeling (see below) | unset |
KEYCLOAK_KNOWN_EGRESS | Comma-separated CIDRs of known shared egress points (VDI, VPN concentrators, partner proxies). spray_check labels matching IPs known_egress: true and marks them confidence: low; they are never excluded | unset |
KEYCLOAK_DEFAULT_DATE_FROM_HOURS | Default look-back window for event tools when date_from is omitted. Set to 0 to scan full history (can hang on large realms). | 24 |
KEYCLOAK_DEADLINE | Per-call wall-clock budget (seconds) for the heavy event/TOTP tools. When a wide window / large realm would exceed it, the tool stops and returns a disclosed partial (⚠️ warning) instead of running past the client's ~60s gateway timeout and hammering KeyCloak. Each request's timeout is also capped at the time left, and nothing is retried past the deadline, so one slow page cannot run a call past it. 0 or negative disables. | 45 |
KEYCLOAK_MAX_EVENTS | Per-pagination cap on events fetched by the event tools (also bounds how deep the slow high-offset pagination goes). Over the cap the result is a disclosed partial. 0 or negative disables. | 200000 |
KEYCLOAK_MAX_USERS | Default cap on users scanned by get_totp_users when its max_users argument is 0 (each user costs one credential call). 0 or negative disables (whole realm, bounded only by KEYCLOAK_DEADLINE). | 5000 |
KEYCLOAK_USER_ATTRIBUTE_WHITELIST | Comma-separated custom user-attribute keys that get_user is allowed to surface. Unset by default: get_user only ever returns username/name/email/enabled/created, since the search endpoint it resolves the username through returns a brief representation with no attributes at all. Opting a key in makes get_user do one extra by-ID lookup and append that attribute's value when present. Everything else stays out of tool output. As a safety net, a whitelisted key whose name looks credential-shaped (contains password, secret, token, etc.) is reported as blocked rather than shown — not a guarantee, since a credential attribute named outside that pattern list still gets through. | unset |
KEYCLOAK_GROUP_WRITE_ROOT | Enables the opt-in group-change tools (plan_group_changes, apply_group_changes) and confines them to groups below this absolute path (e.g. /Staff). Unset, empty or malformed: the two tools are not registered at all. Set it only on a deployment that puts a human approval step in front of the server. | unset |
KEYCLOAK_PROTECTED_GROUPS | ;-separated full group paths that the group-change tools refuse to add to or remove from (descendants included). A malformed entry disables the group-change tools rather than silently dropping the protection. | unset |
KEYCLOAK_GROUP_BATCH_MAX | Maximum rows per group-change call. | 30 |
Topics
keycloakmcp-serverrestapi
Preguntas frecuentes
Lo que la gente pregunta sobre keycloak-mcp
¿Qué es shigechika/keycloak-mcp?
shigechika/keycloak-mcp es mcp servers para el ecosistema de Claude AI. MCP server for the Keycloak Admin REST API — a strong ally for auth troubleshooting: inspect users, sessions, clients, and realm config through AI assistants. Tiene 0 estrellas en GitHub y su última actualización registrada es del 2026-10-22.
¿Cómo se instala keycloak-mcp?
Puedes instalar keycloak-mcp clonando el repositorio (https://github.com/shigechika/keycloak-mcp) o siguiendo las instrucciones del README en GitHub. ClaudeWave también te ofrece bloques de instalación rápida en esta misma página.
¿Es seguro usar shigechika/keycloak-mcp?
Nuestro agente de seguridad ha analizado shigechika/keycloak-mcp y le ha asignado un Trust Score de 95/100 (tier: Verified). Revisa el desglose completo de comprobaciones superadas y flags en esta página.
¿Quién mantiene shigechika/keycloak-mcp?
shigechika/keycloak-mcp es mantenido por shigechika. La última actividad registrada en GitHub es del 2026-10-22, con 8 issues abiertos.
¿Hay alternativas a keycloak-mcp?
Sí. En ClaudeWave puedes explorar mcp servers similares en /categories/mcp, ordenados por popularidad o actividad reciente.