What can you do with this server?

The keycloak-mcp server provides a comprehensive interface to the Keycloak Admin REST API for identity and access management, authenticating via a Service Account. 👤 User Management * Count total users, search by username/email/name, get full user details * Reset a single user's password (optionally temporary) or bulk reset from CSV * View active sessions per user (with local-time timestamps) and force logout 🔐 MFA / Credentials * Get credential types configured for a user (TOTP/HOTP detection) * Analyze realm-wide TOTP adoption with counts, percentages, and optional user list 👥 Groups * List groups a user belongs to and list members of a group 🛡️ Security * Check brute-force lock status for a user * Analyze login failures by source IP (with optional site labeling via INI config) * Detect login redirect loops — flag users with excessive logins in a short time window 📋 Events & Auditing * Query user events (login, password updates, failures) filtered by type, username, client, IP, and date range * View login totals, logins bucketed by hour of day, and logins by client/SP * Query admin events (CREATE/UPDATE/DELETE/ACTION) filtered by operation type, resource, path, and date range * Track custom attribute change history for a specific user 🖥️ Sessions & Clients * Get active session counts per client, list active sessions for a specific client * List all SAML and OIDC clients in the realm and all realm-level roles 🌅 Monitoring & Reporting * Health check — verify server reachability and service account authentication (lightweight) * Daily brief — a one-shot morning report covering login stats, brute-force IPs, active sessions, password updates, and admin events in a Markdown summary with OK/WARNING/CRITICAL tiers

Which integrations are available for this server?

Provides tools for managing Keycloak users, groups, security, events, sessions, and clients through the Keycloak Admin REST API via service account authentication.

How do I use keycloak-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@keycloak-mcp search for user john.doe" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

keycloak-mcp

by shigechika

Overview Schema Related Servers Score Discussions

Python

Remote

keycloak-mcp

English | 日本語

An MCP (Model Context Protocol) server for the KeyCloak Admin REST API.

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. `temp_password`) 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).

Related MCP server: Keycloak MCP Server

Setup

# uv
uv pip install keycloak-mcp

# pip
pip install keycloak-mcp

From 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_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 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.

Verify your setup

After setting the environment variables, run --check to confirm authentication works before wiring it into an MCP client:

export KEYCLOAK_URL=https://keycloak.example.com
export KEYCLOAK_REALM=my-realm
export KEYCLOAK_CLIENT_ID=keycloak-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
keycloak-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:

[hq]
name = HQ (Tokyo)
ipv4 = 192.0.2.0/24, 198.51.100.0/24
ipv6 = 2001:db8:1::/48

[vpn]
name = VPN
ipv4 = 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

In .mcp.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:

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

From a shell

export KEYCLOAK_URL=https://keycloak.example.com
export KEYCLOAK_REALM=my-realm
export KEYCLOAK_CLIENT_ID=keycloak-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
keycloak-mcp

CLI

keycloak-mcp --version   # Print version and exit
keycloak-mcp --help      # Show usage and required environment variables
keycloak-mcp --check     # Verify env vars and authentication, then exit
keycloak-mcp             # Run the MCP STDIO server (default)

No-argument mode is the normal one — that's how MCP clients launch it.

Development

git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp

# uv
uv sync --dev
uv run pytest -v
uv run ruff check .

# pip
python3 -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:

# needs KEYCLOAK_URL / KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET
uv run python scripts/smoke_test.py
uv 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

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

6dRelease cycle

18Releases (12mo)

Commit activity

Issues opened vs closed

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

Keycloak MCP Server
Security Developer Tools App Automation
ChristophEnglisch
A
license
B
quality
D
maintenance
A Model Context Protocol server that provides tools to manage Keycloak users and realms, allowing you to create and delete users, list available realms, and view users in specific realms.
Last updated 2025-02-09
4
99
45
MIT
Keycloak MCP Server
Security Developer Tools
HaithamOumerzoug
A
license
B
quality
D
maintenance
A Model Context Protocol server that enables management of Keycloak users and realms through a standardized interface, providing tools for user creation, deletion, role assignment, and group management.
Last updated 2025-12-01
9
121
12
MIT
Advanced Keycloak MCP server
Developer Tools Security Autonomous Agents
Octodet
A
license
A
quality
C
maintenance
Advanced Keycloak MCP server
Last updated 2025-06-30
7
23
3
MIT
mcp-keycloak
Security Developer Tools
xuancanhit99
A
license
-
quality
D
maintenance
A Model Context Protocol (MCP) server that provides a natural language interface for managing Keycloak identity and access management through its REST API.
Last updated 2026-02-13
MIT

View all related MCP servers

Related MCP Connectors

console-mcp-server
The official MCP Server from Mia-Platform to interact with Mia-Platform Console
Appcircle MCP
MCP server for Appcircle mobile CI/CD platform.
server
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shigechika/keycloak-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

keycloak-mcp

Features

Users

MFA / Credentials

Groups

Security

Events

Admin Events

Sessions & Clients

Morning Patrol

Setup

Configuration

KeyCloak client setup

Verify your setup

IP-to-site labeling (optional)

Usage

Claude Code

Claude Desktop

From a shell

CLI

Development

Live smoke test

License

Maintenance

Resources

Looking for Admin?

Tools

Related MCP Servers

Keycloak MCP Server

Keycloak MCP Server

Advanced Keycloak MCP server

mcp-keycloak

Related MCP Connectors

Latest Blog Posts

MCP directory API