keycloak-mcp

An MCP (Model Context Protocol) server, stdio transport, that lets an AI assistant inspect and — behind explicit guards — modify Keycloak realm, client, and protocol-mapper configuration across multiple Keycloak hosts from a single server process.

Built on the official @keycloak/keycloak-admin-client and the @modelcontextprotocol/sdk. Design derived from the MIT-licensed Octodet keycloak-mcp — see NOTICE.

Install

git clone https://github.com/Faust-Systems/keycloak-mcp.git
cd keycloak-mcp
npm install
npm run build     # tsc → dist/

Then create a config file (see Configuration) and register the server with your MCP client (see Registering with Claude).

Related MCP server: k8s-mcp-server

Hosts

Every tool takes a host argument: a string key naming an entry in the config file's hosts map (or discovered from the KC_<HOST>_* env fallback — see below). Host keys are entirely arbitrary and user-defined — there is no fixed list of hosts baked into this server. Point it at whatever Keycloak instances you like, under whatever names make sense to you (prod-eu, staging, customer-a, ...).

Each host entry carries its own explicit production flag:

"prod-eu": { "url": "...", "adminUser": "", "adminPassword": "", "production": true }

• production: true marks the host as production: writes against it are refused unless allowProdWrite is also true in the config.

• production: false marks it non-production: writes need only the per-call write=true.

The server authenticates per host with a password grant against the admin-cli client on the master realm, and caches the admin client per host (re-authenticating when the token expires). The target realm is a per-call argument on every tool.

Safety model

• Read-only by default. Mutating tools (ensure_hardcoded_claim_mapper, delete_protocol_mapper) take a write boolean that defaults to false. Without write=true they return a dry-run plan and call no mutating API.

• Production gate, fail-closed. Even with write=true, a write against a production host is refused unless allowProdWrite is true in the config file (or, when using the env fallback, KC_ALLOW_PROD_WRITE=true). A host is production whenever its production flag is true, absent, or any non-boolean value — only an explicit production: false opts a host out of the gate. See Hosts.

• No secrets, ever. Admin passwords and tokens are never logged or returned; client secrets and registration access tokens are redacted from get_client output.

• Audit trail. Every successful write emits a structured JSON line to stderr: timestamp, host, realm, clientId, action, mapper name.

• Idempotent verbs. ensure_hardcoded_claim_mapper reconciles toward a desired state (already-present / update-with-diff / create) instead of blindly creating; genuine ambiguity (e.g. two mappers already emitting the claim) is reported as a conflict and never auto-resolved.

Client secrets — the file-sink model

dump_client_secret and regenerate_client_secret handle real client secret values. To keep those values out of the AI model's context entirely, the server never returns or logs the value:

• The secret value is written directly to a local file by the server process (outPath, mode 0600, exact bytes, no trailing newline).

• The tool returns only metadata — { host, realm, clientId, outPath, byteLength } (plus rotated: true for a regeneration). The value is never in the return object, any log line, the audit line, or any error message.

• Keycloak admin-API failures are reduced to an HTTP status plus a generic message, so no response body can leak.

• The server warns (does not fail) if outPath's directory is group/world-writable, since a secret file there could be exposed.

• dump_client_secret is a read (no Keycloak mutation) so it is not write-gated — but it still writes a local file. regenerate_client_secret is a mutation: write=false (default) is a dry run, and rotating a production host requires allowProdWrite (see the fail-closed rule under Hosts).

Configuration

All configuration — host URLs, admin credentials, and the production-write gate — comes from a single JSON config file. Nothing is hardcoded.

File location & precedence

The config path is resolved in this order:

1. The environment variable KEYCLOAK_MCP_CONFIG, if set (explicit override).

2. Otherwise the default ~/.config/keycloak-mcp/config.json.

The file takes precedence. If no file is found at the resolved path, the server falls back to the legacy per-host environment variables (below) so nothing breaks — but when the file is present it is used exclusively and the env vars are ignored.

File shape

See config.example.json. Copy it to ~/.config/keycloak-mcp/config.json and fill in your own host keys and credentials:

{
  "hosts": {
    "prod-eu": { "url": "https://keycloak.example.com",    "adminUser": "", "adminPassword": "", "production": true },
    "staging": { "url": "https://kc-staging.example.com",  "adminUser": "", "adminPassword": "", "production": false }
  },
  "allowProdWrite": false
}

• Host keys ("prod-eu", "staging" above) are entirely arbitrary — name your hosts however makes sense to you. There is no fixed set of hosts; add or remove entries freely.

• production (per host) gates writes behind allowProdWrite. Fail-closed rule: if production is absent, null, or any non-boolean value, the host is treated as production. Only a literal production: false opts a host out. See Hosts.

• allowProdWrite must be true to permit writes to any host whose production flag resolves to production (per the rule above); a host explicitly marked production: false only needs the per-call write=true.

• A host with a missing url, adminUser, or adminPassword fails only when addressed, with an error naming the missing field names (never values). The other hosts keep working.

• Calling a tool with a host key that isn't in the config fails with an error naming the requested host and listing the configured host keys (never values).

Protect the file: it holds admin credentials in the clear. Keep it at chmod 600 — the server prints a one-line warning to stderr (it does not refuse) if the file is group- or world-readable.

Environment-variable fallback

Used only when no config file exists at the resolved path. See .env.example.

Host keys are discovered by scanning for a KC_<HOST>_URL variable — there is no fixed list. The host key is the captured part of the variable name, lowercased, with underscores left as-is: KC_PROD_EU_URL yields the host key prod_eu. Hyphens in a host key are not expressible via env vars — use the config file if you need one.

Build

npm install
npm run build     # tsc → dist/
npm test          # vitest unit tests

Registering with Claude (MCP config)

Because all credentials live in the config file, the MCP registration needs only command + args — no env block:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/keycloak-mcp/dist/index.js"]
    }
  }
}

The server reads ~/.config/keycloak-mcp/config.json by default. To point it at a different file, add a single override:

"env": { "KEYCLOAK_MCP_CONFIG": "/absolute/path/to/config.json" }

Keep allowProdWrite at false in the file to hold production read-only; set it to true only when a session must change production.

Tools

Usage example — hardcoded realm claim

Goal: the my-app client in realm acme on the staging host (configured with "production": false, see Hosts) must emit a hardcoded realm claim with value acme in access tokens.

1. Dry run (default — nothing changes):

   ensure_hardcoded_claim_mapper with { "host": "staging", "realm": "acme", "clientId": "my-app", "claimName": "realm", "claimValue": "acme" }

   → returns status: "dry-run", wouldDo: "create" with the exact mapper it would create — or wouldDo: "update" with a per-key diff if a mapper already exists with different config, or status: "already-present" if everything already matches.

2. Apply: same call plus "write": true.

   → creates/updates the mapper and emits an audit line to stderr.

3. Repeat against a production host (e.g. prod-eu) once verified — those calls additionally require "allowProdWrite": true in the config file.

Development

• src/index.ts — server bootstrap + tool registration (stdio).

• src/config.ts — config file loader (file → env fallback), perms warning.

• src/hosts.ts — host registry, config validation, production write gate.

• src/kc.ts — cached, re-authenticating admin client per host.

• src/mappers.ts — pure plan/diff logic for the ensure tool (unit-tested).

• src/secrets.ts — client-secret file-sink tools (value never returned/logged).

• src/redact.ts — secret redaction.

• src/audit.ts — stderr audit lines.

• test/ — vitest unit tests for all pure logic.

License

MIT — see LICENSE. Derived from the design of Octodet's keycloak-mcp; see NOTICE for attribution.