io.github.ChristophEnglisch/keycloak-model-context-protocol

Keycloak MCP Server

A Model Context Protocol (MCP) server for Keycloak administration. It lets an AI assistant such as Claude manage users, groups, roles and sessions, and inspect clients, events and the security posture of your realms, through the Keycloak Admin REST API, with least-privilege authentication and guardrails around every write.

[!WARNING] This server acts with the permissions of the Keycloak account you give it. Use a dedicated service-account client with only the roles you need, never the bootstrap admin. Destructive tools ask for confirmation by default, and a read-only mode is available. See Security.

Highlights

• 24 tools in 7 toolsets, enabled per toolset. The default set (core, groups, roles) is small; everything else is opt-in.
• Least-privilege auth. client_credentials with a service account is the recommended grant; the password grant stays available. No credential defaults, so a missing setting fails fast.
• Guardrails. Read-only mode, realm allowlist, write protection for the master realm, and a preview-then-confirm: true flow for destructive operations.
• 4 guided prompts (onboarding, offboarding, security audit, failed-login investigation) and MCP resources for realms and users, with realm-name completion.
• Structured, paginated output with output schemas; secrets and credentials are never returned or logged.
• Works with Claude Desktop, Claude Code, VS Code, Cursor and any stdio MCP client. Requires Node.js 22 or newer.

How it works

Your MCP client starts the server as a local child process and talks to it over stdio. Every tool call passes the guards, then goes through a single gateway that owns the Keycloak login and caches the access token.

What a destructive call looks like

A destructive tool never acts on the first call. It returns a preview of what would happen and changes nothing. Only after you approve does the assistant repeat the call with confirm: true.

Quick start

Requirements: Node.js 22 or newer, a Keycloak server your machine can reach (tested with Keycloak 24.0 to 26.8), and an MCP client.

1. Prepare Keycloak (3 steps)

In the realm you want to administer (here demo):

1. Create a client mcp-admin with Client authentication on and only Service accounts roles enabled (turn off Standard flow and Direct access grants).
2. Assign roles. On the client's Service accounts roles tab, assign client roles of realm-management. For a first read-only trial: view-users, query-users, query-groups, view-realm.
3. Copy the secret from the client's Credentials tab.

Step-by-step instructions with Admin Console click paths, kcadm.sh commands and a local Docker Keycloak: docs/getting-started.md.

2. Configure your MCP client

Example for Claude Code (other clients: docs/clients.md):

claude mcp add --transport stdio \
  --env KEYCLOAK_URL=https://keycloak.example.com \
  --env KEYCLOAK_AUTH_REALM=demo \
  --env KEYCLOAK_CLIENT_ID=mcp-admin \
  --env KEYCLOAK_CLIENT_SECRET="$KEYCLOAK_CLIENT_SECRET" \
  keycloak -- npx -y keycloak-model-context-protocol

Or as JSON (Claude Desktop, claude_desktop_config.json):

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "keycloak-model-context-protocol"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_AUTH_REALM": "demo",
        "KEYCLOAK_CLIENT_ID": "mcp-admin",
        "KEYCLOAK_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}

3. Ask your first question

List the realms you can access, then show me the first 10 users of realm demo.

If you get an answer, you are done. If not, see docs/troubleshooting.md.

Configuration

All settings are environment variables. Only KEYCLOAK_URL and one set of credentials are required.

Full reference with examples, validation rules and the tool-to-role matrix: docs/configuration.md.

Toolsets and tools

Tools are named <domain>_<verb>. Only the default toolsets are enabled unless you set KEYCLOAK_MCP_TOOLSETS. In read-only mode only tools of kind read are registered.

Details for every tool (parameters, outputs, required roles): docs/tools-reference.md.

Prompts and resources

Prompts are guided workflows built on the tools. They appear in your client's prompt picker (in Claude Code as slash commands). The realm argument autocompletes.

Resources are read-only JSON documents, filtered by the same realm allowlist:

Security

• Least privilege first. Use a service-account client scoped to one realm with only the realm-management roles you need. A role matrix is in docs/configuration.md.
• Destructive operations need confirmation (KEYCLOAK_MCP_REQUIRE_CONFIRMATION=true), and granting administrative roles does too.
• Blast-radius limits: KEYCLOAK_MCP_READ_ONLY, KEYCLOAK_MCP_REALMS, and write protection for master (off by default).
• No secrets in output or logs. Credentials are masked on stderr; tools never return client secrets, user credentials or attributes.
• Prompt injection: treat names and descriptions coming from Keycloak as data. The shipped prompts say so explicitly; keep write tools disabled when you do not need them.

Threat model, hardening checklist and how to report a vulnerability: docs/security.md and SECURITY.md.

Example prompts

• "Which realms can you see? Show me the settings of realm demo."
• "Find all users in demo whose e-mail ends with @example.com and who are disabled."
• "Create user jdoe (Jane Doe, jane@example.com) in demo, add her to group engineering and send her an e-mail to set a password."
• "Who is in the group ops, and which roles does alice have, including composite roles?"
• "Run the audit_realm_security prompt for demo." (needs clients and events toolsets for the full audit)
• "There were many failed logins last night. Investigate realm demo."
• "Offboard bob in demo: end his sessions and disable the account."

Documentation

Upgrade from 0.x

Version 1.0 changes the defaults: credentials are required (no admin/admin fallback), destructive tools ask for confirmation, and the tools were renamed to <domain>_<verb> (for example create-user became user_create, delete-user became user_delete). The old KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD variables still work but are deprecated. See the migration guide.

Contributing and license

Contributions are welcome. See CONTRIBUTING.md and the Code of Conduct. Released under the MIT License.