keycloak-mcp: Instructions file for Claude Code

CLAUDE.md

Overview

MCP server for the KeyCloak Admin REST API. Authenticates as a Service Account (OIDC Client Credentials Grant — no human password or TOTP); never calls the userinfo endpoint and never creates user sessions (the project describes this as "Infinispan-safe" — see README.md). Exposes 33 tools (users, MFA/credentials, groups, brute-force/security, events, admin events, sessions/clients, and a daily_brief morning report) over stdio transport, plus two opt-in group-change tools (plan_group_changes, apply_group_changes) registered only when KEYCLOAK_GROUP_WRITE_ROOT is set.

Commands

uv sync --dev
uv run pytest -v                  # all tests
uv run ruff check .               # lint
uv run ruff format --check .      # format check

This mirrors .github/workflows/ci.yml (matrix: Python 3.10–3.14 on Ubuntu, plus one Windows 3.12 job to catch stdio newline regressions). Plain-pip equivalents are documented in README.md's Development section.

Architecture

• keycloak_mcp/auth.py — TokenManager: Client Credentials Grant token fetch/cache, refreshed 30s before expiry.
• keycloak_mcp/client.py — KeyCloakClient: thin httpx wrapper over the Admin REST API; retries 429/502/503/504 and transport errors with exponential backoff; _paginate pages list endpoints.
• keycloak_mcp/sites.py — SiteClassifier: labels IPs with a site name from an optional KEYCLOAK_SITES_INI file.
• keycloak_mcp/server.py — MCPServer (mcp 2.x) server; all @mcp.tool() functions.
• keycloak_mcp/group_changes.py — opt-in group moves: plan_changes / apply_changes (policy, digest, add-before-remove with read-back).
• keycloak_mcp/__main__.py — CLI entry point (--check, --version) plus a Windows-only stdout wrapper that strips CRLF back to LF.

Required env vars: KEYCLOAK_URL, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET. Optional: KEYCLOAK_REALM (default master), KEYCLOAK_SITES_INI, KEYCLOAK_DEFAULT_DATE_FROM_HOURS (default 24), and the heavy-tool bounds KEYCLOAK_DEADLINE (default 45s), KEYCLOAK_MAX_EVENTS (default 200000), KEYCLOAK_MAX_USERS (default 5000) — a wall-clock deadline + caps so a wide event window or a whole-realm get_totp_users returns a disclosed partial (⚠️) instead of blowing the ~60s gateway and hammering KeyCloak (see _paginate's deadline/max_total and server.py's _deadline_seconds/_max_events/_max_users). Each 0/negative disables. Group changes (keycloak_mcp/group_changes.py, registered by server.register_group_tools): KEYCLOAK_GROUP_WRITE_ROOT (unset = tools not registered), KEYCLOAK_PROTECTED_GROUPS (;-separated full paths, each must exist), KEYCLOAK_GROUP_BATCH_MAX (default 30), KEYCLOAK_GROUP_MODE (multi default / single = adding replaces every other membership, no DELETE sent), KEYCLOAK_GROUP_DEADLINE (default KEYCLOAK_DEADLINE). The digest is a staleness check, not an approval token; the approval gate belongs to the client. Configuration snapshots (keycloak_mcp/config_snapshot.py): KEYCLOAK_STATE_DIR (unset = none). Only daily_brief writes (first run of a day, complete reads only); get_config_changes compares and never writes. Secret-named string values are redacted before storing. KEYCLOAK_USER_ATTRIBUTE_WHITELIST (default unset, comma-separated attribute keys) opts specific custom user attributes into get_user's output — unset, get_user never fetches or surfaces attributes at all (see _user_attribute_whitelist/get_user_by_id), so no custom attribute reaches tool output, hence LLM context, unless an operator explicitly names it. A whitelisted key that matches _looks_like_credential_key's substring list (password, secret, token, …) is reported as blocked rather than shown — a safety net on top of the whitelist, not a guarantee for arbitrarily-named credential attributes.