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 confirmed call looks like

Every tool that changes data is destructive (it deletes or revokes) or sensitive (it changes identity, credentials, rights or protection mechanisms, for example user_update or user_role_assign). Called without confirm: true, such a tool only returns a preview of what would happen and changes nothing. After you approve, the assistant repeats the call with confirm: true.

The model can set confirm: true itself, even on its first call. The server then still computes the preview and returns it with the result, but only your client's approval prompt proves that a human agreed. All these tools carry destructiveHint, so clients that ask before destructive calls ask here too.

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@1

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

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "keycloak-model-context-protocol@1"],
      "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.
• Every change needs confirmation (KEYCLOAK_MCP_REQUIRE_CONFIRMATION=true): destructive and sensitive tools show a preview first. Grants of administrative rights, also through composite roles and parent groups, profile changes and action e-mails for accounts with administrative rights, and changes to the server's own account need a confirmation that KEYCLOAK_MCP_REQUIRE_CONFIRMATION=false does not turn off. Role and group grants, profile changes and action e-mails for the server's own account are refused.
• Account takeover protection: a changed e-mail address is marked as unverified unless stated otherwise, action e-mail links are valid for at most 24 hours, and previews name the recipient address and whether the target account has administrative rights.
• 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, [email protected]) 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.