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. Every tool that changes data asks 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 every change. Grants of administrative rights are detected through composite roles and parent groups.
• 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 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": " " } } } }

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 _ . 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 firs