Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@keycloak-mcp-server List all users in the master realm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Administer Keycloak through the Model Context Protocol (MCP) — manage realms, clients, users, roles, groups, identity providers and sessions from any MCP client (Claude Code, Claude Desktop, Cursor, …).
Status: early. The first tool slice (realms/clients/users read) is working; the full admin surface is on the roadmap below.
npm install
npm run buildRelated MCP server: keycloak-mcp
The server talks to the Keycloak Admin REST API. Provide credentials via environment variables
(see .env.example):
Variable | Default | Notes |
|
| Base URL |
|
| Auth realm (master can administer all realms) |
|
| Client used for the grant |
|
| Password grant |
| — | If set, uses a client-credentials (service account) grant instead |
| — | Set |
| — | Comma-separated allowlist to register only some tool groups (default: all). Groups: |
| — | If set, serve remote Streamable HTTP at |
With KEYCLOAK_MCP_HTTP_PORT the server runs a stateless Streamable HTTP endpoint at /mcp, gated
by a bearer token. Pick a mode:
Variable | Notes |
| OAuth2 mode (recommended). Validates the caller's JWT against this issuer's JWKS — e.g. protect the server with the very Keycloak it administers. Serves RFC 9728 Protected Resource Metadata at |
| Optional JWKS override (defaults to |
| Optional expected |
| Optional realm role the caller must hold ( |
| Static mode. A shared secret compared in constant time — simple single-caller setups |
| The externally-visible base URL (used in the metadata document) |
If neither an OIDC issuer nor a static token is set, HTTP mode binds to 127.0.0.1 only and
refuses to expose an unauthenticated Keycloak admin endpoint on a public interface.
claude mcp add keycloak node /absolute/path/to/keycloak-mcp-server/dist/index.js \
--env KEYCLOAK_URL=http://localhost:8081 \
--env KEYCLOAK_ADMIN_USER=admin \
--env KEYCLOAK_ADMIN_PASSWORD=adminFull MCP spec, not just tools:
Tools (113) — the complete Keycloak admin API (catalog below).
Resources — read-only state as context: keycloak://realms, keycloak://server-info, and the
templates keycloak://realm/{realm}, .../clients, .../roles (the {realm} variable
autocompletes from the live server).
Prompts — guided admin workflows: audit_realm_security, diagnose_login_failures,
onboard_client, rotate_client_secret (realm / clientId arguments autocomplete).
Completion — completion/complete for the prompt + resource-template arguments above.
Logging — the logging capability is advertised; logging/setLevel is honored and each tool
invocation is logged to the client at the requested level.
Tool annotations — every tool carries readOnlyHint / destructiveHint / idempotentHint, so
clients can render and gate reads vs. destructive writes differently.
Resource subscriptions — resources/subscribe is supported; a subscribed URI is polled and the
server emits notifications/resources/updated when its content changes.
Sampling — kc_ai_review asks the connected client's LLM to review a realm's security posture.
Elicitation — kc_delete_realm_interactive confirms with the user via elicitation/create
instead of a confirm flag. Both degrade gracefully if the client lacks the capability.
Area | Status |
JSON-RPC 2.0, lifecycle, capability negotiation, ping, cancellation | ✅ (SDK) |
Pagination, progress | ✅ (SDK) |
Tools · Resources · Prompts · Completion · Logging | ✅ |
Resource subscriptions ( | ✅ |
Sampling · Elicitation (client features the server uses) | ✅ |
Transports: stdio · Streamable HTTP | ✅ |
Authorization: OAuth2 Resource Server on HTTP (RFC 9728) | ✅ |
113 tools across the full Keycloak admin surface. All write tools are refused when
KEYCLOAK_MCP_READONLY is set; every destructive tool (delete/clear/logout/regenerate) is a
dry-run unless confirm=true.
Core reads (10)
Tool | Description |
| List all realms (name + enabled flag). |
| Get a realm's configuration summary. |
| List OAuth clients in a realm. |
| Get a client by its clientId. |
| List client scopes in a realm. |
| List users in a realm (paged). |
| Get a single user by id or (exact) username. |
| List realm roles. |
| List groups in a realm. |
| List identity providers (SSO / social login) in a realm. |
Users — core writes (5)
Tool | Description |
| Create a user in a realm (optionally set an initial password). |
| Enable or disable a user. |
| Assign a realm role to a user. |
| Remove a realm role from a user. |
| Delete a user (destructive). Dry-run unless confirm=true. |
Users — lifecycle & roles (12)
Tool | Description |
| Update a user's profile fields; attributes are merged into existing ones. |
| Count users in a realm, optionally filtered. |
| List a user's active sessions. |
| Log a user out of ALL sessions (destructive). Dry-run unless confirm=true. |
| Set a user's password (temporary=true forces change on next login). |
| Send the email-verification email to a user. |
| Email a user a link to perform required actions (e.g. UPDATE_PASSWORD, CONFIGURE_TOTP). |
| Remove a user from a group. |
| List the groups a user belongs to. |
| List a user's realm-role and client-role mappings. |
| Assign a client role to a user (client resolved by clientId, role by name). |
| Remove a client role from a user (client resolved by clientId, role by name). |
Clients — full management (12)
Tool | Description |
| Update a client (merge: only provided fields change). |
| Get the current secret of a confidential client. |
| Rotate a client's secret (destructive: old secret stops working). Dry-run unless confirm=true. |
| Get the service-account user of a client (serviceAccountsEnabled). |
| Attach a client scope (by name) as a DEFAULT scope of a client. |
| Detach a DEFAULT client scope (by name) from a client. |
| Attach a client scope (by name) as an OPTIONAL scope of a client. |
| Detach an OPTIONAL client scope (by name) from a client. |
| List protocol mappers of a client. |
| Create a protocol mapper on a client (config passed through as-is). |
| Delete a protocol mapper (by name) from a client (destructive). Dry-run unless confirm=true. |
| List roles defined on a client. |
Clients / roles / groups / scopes — core writes (9)
Tool | Description |
| Create an OIDC client in a realm. |
| Delete a client by clientId (destructive). Dry-run unless confirm=true. |
| Create a realm role. |
| Delete a realm role by name (destructive). Dry-run unless confirm=true. |
| Create a group in a realm. |
| Delete a group by id (destructive). Dry-run unless confirm=true. |
| Add a user to a group. |
| Create a client scope. |
| Delete a client scope by id (destructive). Dry-run unless confirm=true. |
Realms (9)
Tool | Description |
| Create a new realm. |
| Update realm settings (partial RealmRepresentation passthrough). |
| Delete a realm and everything in it (destructive). Dry-run unless confirm=true. |
| Get a realm's login/admin event logging configuration. |
| Update a realm's event logging config (only provided fields change). |
| Clear the server-side realm cache (destructive-ish). Dry-run unless confirm=true. |
| Clear the server-side user cache (destructive-ish). Dry-run unless confirm=true. |
| List a realm's active key metadata (no key material blobs). |
| Get Keycloak server info (version, features, themes). |
Roles — composites & client roles (8)
Tool | Description |
| Update a realm role's description. |
| List the composite (child) roles of a realm role. |
| Add realm roles (by name) as composites of a realm role. |
| Remove composite roles (by name) from a realm role (destructive). Dry-run unless confirm=true. |
| List users holding a realm role. |
| Create a role on a client (resolved by clientId). |
| Update a client role's description (client resolved by clientId). |
| Delete a client role (destructive; client resolved by clientId). Dry-run unless confirm=true. |
Groups — members & mappings (7)
Tool | Description |
| Get a single group by id, including its direct subgroups. |
| Update a group's name and/or attributes. |
| List members of a group (paged). |
| Create a child group under a parent group. |
| Map a realm role onto a group (members inherit it). |
| Remove a realm-role mapping from a group (destructive). Dry-run unless confirm=true. |
| List a group's role mappings (realm + client roles). |
Client scopes — mappers & realm defaults (8)
Tool | Description |
| Get a client scope by id or name (includes protocol mappers). |
| Update a client scope's name/description/protocol/attributes (locate by scopeId or name). |
| List protocol mappers on a client scope. |
| Add a protocol mapper to a client scope. |
| Delete a protocol mapper from a client scope (destructive). Dry-run unless confirm=true. |
| List the realm's default and/or optional client scopes (assigned to new clients). |
| Add a client scope to the realm's default or optional list (locate by scopeId or name). |
| Remove a client scope from the realm's default or optional list (destructive). Dry-run unless confirm=true. |
Identity providers (7)
Tool | Description |
| Get a single identity provider by alias (clientSecret masked). |
| Create an identity provider (e.g. oidc, saml, google, github). |
| Update an identity provider; config keys are merged into the existing config. |
| Delete an identity provider by alias (destructive). Dry-run unless confirm=true. |
| List mappers of an identity provider. |
| Create a mapper on an identity provider. |
| Delete an identity-provider mapper by id (destructive). Dry-run unless confirm=true. |
Sessions, events & brute-force (7)
Tool | Description |
| List admin (audit) events with optional operation/resource/date filters. |
| List user (login) events with optional type/user/date filters. |
| Clear ALL admin (audit) events in a realm (destructive). Dry-run unless confirm=true. |
| Clear ALL user (login) events in a realm (destructive). Dry-run unless confirm=true. |
| Active/offline session counts per client in a realm. |
| Brute-force (attack detection) lockout status for a user. |
| Clear brute-force lockout for one user (userId) or ALL users (destructive). Dry-run unless confirm=true. |
Authentication flows (7)
Tool | Description |
| List authentication flows in a realm. |
| List the executions of an authentication flow by flow alias. |
| List required actions registered in a realm. |
| Update a required action by alias (merge: only provided fields change). |
| Move a required action one position down in the priority order. |
| Copy an authentication flow (by source alias) to a new flow name. |
| Delete a non-built-in authentication flow by id (destructive). Dry-run unless confirm=true. |
Organizations & components (10)
Tool | Description |
| List organizations in a realm, optionally filtered by search text. |
| Get one organization by id. |
| Create an organization with a name and one or more email domains. |
| Delete an organization by id (destructive). Dry-run unless confirm=true. |
| List members of an organization. |
| Add an existing realm user to an organization. |
| Remove a user from an organization (destructive). Dry-run unless confirm=true. |
| List realm components (user federation, key providers), filterable by provider type. |
| Get one component by id, including its config. |
| Delete a component by id (destructive). Dry-run unless confirm=true. |
Sampling & elicitation (2)
Tool | Description |
| Ask the connected client's LLM to review a realm's security posture (MCP sampling). Read-only. |
| Delete a realm, confirming via MCP elicitation (asks the user directly — no confirm arg). Refused in read-only mode. |
Credential flows: BCrypt hash-import for app migrations.
Sampling / elicitation for interactive, confirmation-gated write workflows.
This server cannot be deployed
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Remote MCP for A2A caller identity, scope policy, verdict receipts, and audit history.
