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

MFA / Credentials

Groups

Security

Events

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.

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

Morning Patrol

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

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.

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.

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.

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

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 (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:

{
  "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.

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:

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

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