mcp-keycloak-admin
The mcp-keycloak-admin server lets you administer a Keycloak instance through its Admin REST API, covering users, roles, clients, groups, identity providers, federation, authentication, authorization, events, and realm configuration.
User Management
Search, get, create, update, enable/disable, and delete users
Reset passwords, send action emails (e.g. VERIFY_EMAIL), log out users, and list active sessions
Role Management
List realm and client roles
Assign/unassign realm and client roles to users
Assign realm roles to groups
Client Management
List, get, create, update, and delete clients
Get and regenerate client secrets
Manage client scopes (list, assign/unassign default scopes) and protocol mappers
Group Management
List, create, and delete groups
Add/remove users from groups, list group members, and list a user's groups
Identity Provider Management
List, get, create, and delete identity providers
List an identity provider's mappers
User Federation
List and get federation providers (LDAP/Kerberos)
Trigger full or incremental user sync
Authentication & Authorization
List authentication flows and required actions; enable/disable required actions
List authorization resources, policies, and permissions for a client
Events & Monitoring
Read recent login events (filterable by type/user) and admin events
Realm & Server Info
Read key realm configuration flags
Get Keycloak server version and profile info
Safety Features
Read-only mode to prevent any write operations
Restrict operations to allowed realms only
Explicit confirmation required for all destructive operations (delete, reset, logout, etc.)
Supports
service_accountandpasswordauthentication modes
Administer a Keycloak instance through its Admin REST API, providing tools for managing users, roles, clients, groups, identity providers, authentication flows, events, and more.
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., "@mcp-keycloak-admin search for user by username jdoe"
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.
mcp-keycloak-admin
A Model Context Protocol (MCP) server to administer a Keycloak instance through its Admin REST API. Safe by default, configurable, and built with a clean, test-driven architecture.
Compatible with Keycloak 26.x (validated against 26.0.5).
Install
No install needed — run it straight from npm with npx:
npx -y mcp-keycloak-adminThe server speaks MCP over stdio, so you normally wire it into an MCP client rather than running it by hand — see Usage with an MCP client. New to it? The Quickstart spins up a local Keycloak and a client config in a couple of minutes.
Related MCP server: Keycloak MCP Server
Why
Administering Keycloak from an MCP client (an assistant, an IDE, a custom agent) means exposing day-to-day operations — searching users, managing roles, reading events — as MCP tools, without handing over a raw admin console. This server does that with strong guardrails so destructive actions never happen silently.
Features
Two authentication modes, selectable by configuration:
service_account— a confidential client with a service account (recommended; no admin password stored).password— theadmin-cliclient with an admin username/password.
Safe by default:
READ_ONLYmode hides every write/destructive tool.ALLOWED_REALMSrestricts which realms the server may operate on.Destructive operations require explicit confirmation (native MCP elicitation, with a
confirm: trueparameter fallback for clients that do not support elicitation).
Clean Architecture: a framework-free domain, application use cases, and infrastructure adapters. No business concept travels as a raw string or number — every one is a validated value object.
Requirements
Node.js >= 20
A reachable Keycloak 26.x server
Usage with an MCP client
Add the server to your MCP client configuration:
{
"mcpServers": {
"keycloak-admin": {
"command": "npx",
"args": ["-y", "mcp-keycloak-admin"],
"env": {
"KEYCLOAK_BASE_URL": "http://localhost:8080",
"KEYCLOAK_REALM": "demo-realm",
"AUTH_MODE": "service_account",
"KC_CLIENT_ID": "mcp-admin",
"KC_CLIENT_SECRET": "your-secret"
}
}
}
}See docs/setup-keycloak.md to create the mcp-admin
client and grant it the least-privilege roles it needs.
Multiple Keycloak instances
Each server entry targets one Keycloak (one base URL + realm + auth). To manage several environments, add one entry per instance — each fully isolated, with its own credentials and guardrails:
{
"mcpServers": {
"kc-preprod": {
"command": "npx",
"args": ["-y", "mcp-keycloak-admin"],
"env": {
"KEYCLOAK_BASE_URL": "https://preprod.example.com",
"KEYCLOAK_REALM": "preprod-realm",
"AUTH_MODE": "service_account",
"KC_CLIENT_ID": "mcp-admin",
"KC_CLIENT_SECRET": "…",
"ALLOWED_REALMS": "preprod-realm"
}
},
"kc-prod": {
"command": "npx",
"args": ["-y", "mcp-keycloak-admin"],
"env": {
"KEYCLOAK_BASE_URL": "https://auth.example.com",
"KEYCLOAK_REALM": "prod-realm",
"AUTH_MODE": "service_account",
"KC_CLIENT_ID": "mcp-admin",
"KC_CLIENT_SECRET": "…",
"READ_ONLY": "true",
"ALLOWED_REALMS": "prod-realm"
}
}
}
}The client namespaces the tools per server (e.g. kc-prod:keycloak_user_delete),
so there's no risk of running an operation against the wrong environment. This
is the recommended pattern: you can, for example, keep production READ_ONLY
while preprod stays writable.
Configuration
Variable | Required | Description |
| yes | Base URL of the Keycloak server (no trailing slash). |
| yes | Realm the server operates on. |
| yes |
|
| if | Confidential client id (e.g. |
| if | Client secret. |
| if | Admin username. |
| if | Admin password. |
| no (default | Realm holding the admin user ( |
| no (default | When |
| no | Comma-separated allow-list of realms. Empty = all. |
A full example lives in .env.example.
Tools
Levels: [R] read-only · [W] write · [D] destructive (requires
confirmation). Every tool carries the matching MCP annotations
(readOnlyHint / destructiveHint / idempotentHint).
Currently implemented:
Note: this table tracks the
mainbranch, which can run ahead of the latest npm release shown by the version badge above. To confirm what's available in your install, checknpm view mcp-keycloak-admin versionand pinmcp-keycloak-admin@latest.
Tool | Level | Description |
| R | Search realm users by email, username or free text. |
| R | Fetch a single user by id. |
| R | List a user's active sessions. |
| W | Create a realm user. |
| W | Update a user's email, name or enabled flag. |
| W | Enable or disable a user. |
| W | Send a required-actions email. |
| D | Set a new password for a user. |
| D | Revoke all of a user's sessions. |
| D | Permanently delete a user (id + username must match). |
| R | List realm roles. |
| R | List a user's realm roles. |
| W | Grant a realm role to a user. |
| D | Revoke a realm role from a user. |
| R | List the roles defined on a client. |
| R | List a user's client roles. |
| W | Grant a client role to a user. |
| D | Revoke a client role from a user. |
| R | List the realm clients. |
| W | Create a realm client. |
| W | Update a client (enabled, public, redirect URIs, CORS web origins). |
| D | Delete a client. |
| R | Fetch a client by its clientId. |
| R | Read a client secret (masked unless |
| R | List the realm's client scopes. |
| R | List a client's default scopes. |
| R | List a client's protocol mappers. |
| W | Add a default scope to a client. |
| D | Remove a default scope from a client. |
| D | Regenerate a client secret (old one stops working). |
| R | List the realm's top-level groups. |
| R | List the members of a group. |
| R | List the groups a user belongs to. |
| W | Create a top-level group. |
| W | Add a user to a group. |
| W | Grant a realm role to a group. |
| D | Remove a user from a group. |
| D | Delete a group. |
| R | List identity providers. |
| R | Fetch an identity provider by alias. |
| R | List an identity provider's mappers. |
| W | Create an identity provider. |
| D | Delete an identity provider. |
| R | List user federation (LDAP/Kerberos) providers. |
| R | Fetch a federation provider by id. |
| W | Trigger a user sync (full or changed). |
| R | List authentication flows. |
| R | List required actions. |
| W | Enable/disable a required action. |
| R | List a client's authorization resources. |
| R | List a client's authorization policies. |
| R | List a client's authorization permissions. |
| R | Read recent login events (filterable). |
| R | Read recent admin events. |
| R | Read key realm configuration flags. |
| R | Read the Keycloak server version. |
See docs/users.md, docs/roles.md, docs/clients.md, docs/groups.md and docs/events-realm.md for parameters and examples, and docs/security.md for the safety model.
Roadmap
The architecture is designed to keep growing as thin use cases + tools. Remaining candidates: authorization policy/permission CRUD and evaluation, authentication flow mutation (copy/add executions), and advanced federation and identity-provider configuration. See docs/development.md for how to add one.
Development
npm install
npm test # unit tests
npm run test:integration # spins up a real Keycloak 26 via Testcontainers (needs Docker)
npm run check # typecheck + lint + format check + unit tests
npm run build # bundle to dist/Releases are automated — see docs/releasing.md.
Contributing
Contributions are welcome — please read CONTRIBUTING.md.
License
Available Tools
56 toolskeycloak_auth_flows_listList authentication flowsARead-onlyIdempotent
Lists every authentication flow defined in the currently configured Keycloak realm. This is a read-only, idempotent operation that takes no parameters and does not modify any data. Returns a JSON array of flow objects (including alias, description, provider id, top-level and built-in indicators) as formatted text. Use it to inspect or audit the realm's login, registration, and reset-credential flows before configuring related authentication settings.
Inputs: no named parameters.
keycloak_auth_required_action_set_enabledEnable or disable a required actionAIdempotent
Enables or disables a single required action in the currently configured Keycloak realm, identified by its alias. This is a write operation that is not destructive and is idempotent: setting an already-matching state leaves the action unchanged. Call keycloak_auth_required_actions_list first to obtain valid aliases. Returns a short text confirmation stating whether the action was enabled or disabled.
Inputs: alias (required), enabled (required).
keycloak_auth_required_actions_listList required actionsARead-onlyIdempotent
Lists every required action configured in the currently configured Keycloak realm (for example Verify Email, Update Password, or Configure OTP). This is a read-only, idempotent operation that takes no parameters and does not change any data. Returns a JSON array of required-action objects (including alias, name, enabled, defaultAction, and priority) as formatted text. Use it to discover available aliases before enabling or disabling a required action with keycloak_auth_required_action_set_enabled.
Inputs: no named parameters.
keycloak_authz_permissions_listList authorization permissionsARead-onlyIdempotent
Lists the authorization-services permissions defined on a Keycloak client (the bindings that tie resources and/or scopes to the policies that govern them). Read-only and idempotent: it performs no writes and returns the same data for unchanged configuration. Use it to see how a client's resources are protected; call keycloak_clients_list first to obtain the client's internal id, and pair with keycloak_authz_resources_list and keycloak_authz_policies_list for full context. Returns a JSON array of permission entries, or the text "Client not found." when no client matches the given id.
Inputs: clientId (required).
keycloak_authz_policies_listList authorization policiesARead-onlyIdempotent
Lists the authorization-services policies defined on a Keycloak client (the rules, such as role, user, or JS policies, that decide whether access is granted). Read-only and idempotent: it performs no writes and returns the same data for unchanged configuration. Use it to review the policies that back a client's permissions; call keycloak_clients_list first to obtain the client's internal id, and combine with keycloak_authz_resources_list and keycloak_authz_permissions_list to understand the whole authorization model. Returns a JSON array of policy entries, or the text "Client not found." when no client matches the given id.
Inputs: clientId (required).
keycloak_authz_resources_listList authorization resourcesARead-onlyIdempotent
Lists the authorization-services resources defined on a Keycloak client (the protected resources that policies and permissions apply to). Read-only and idempotent: it performs no writes and returns the same data for unchanged configuration. Use it to inspect a client's fine-grained authorization model; call keycloak_clients_list first to obtain the client's internal id, and pair it with keycloak_authz_policies_list and keycloak_authz_permissions_list for the full picture. Returns a JSON array of resource entries, or the text "Client not found." when no client matches the given id.
Inputs: clientId (required).
keycloak_client_createCreate clientA
Create a new OAuth/OIDC client in the configured realm. This is a write operation and is not idempotent: calling it again with the same clientId creates a conflict rather than reusing the existing client. Use keycloak_client_list or keycloak_client_get first to verify the clientId is not already taken, and keycloak_client_update to modify an existing client. Returns a confirmation message naming the created client.
Inputs: clientId (required), enabled, webOrigins, publicClient, +1 more.
keycloak_client_default_scopes_getGet a client's default scopesARead-onlyIdempotent
Lists the default client scopes currently assigned to a single client. This is a read-only, idempotent operation that does not modify Keycloak. Use it to inspect a client's effective default scopes before assigning or unassigning one; for the full catalog of available scopes use keycloak_client_scopes_list instead. Returns a JSON array of the assigned scopes (each with id, name, and protocol), or the text "Client not found." when no client matches the given clientId.
Inputs: clientId (required).
keycloak_client_deleteDelete clientADestructive
Permanently delete a client from the realm. This is a destructive operation and is not idempotent: once deleted, deleting the same clientId again fails because it no longer exists. Requires explicit confirmation via confirm=true (otherwise it aborts without deleting). Use keycloak_client_get to verify the target first, and keycloak_client_update to merely disable a client instead of removing it. Returns a confirmation message, or a reason string when not deleted.
Inputs: clientId (required), confirm.
keycloak_client_getGet clientARead-onlyIdempotent
Fetch a single realm client by its clientId. Read-only and idempotent; it does not modify anything. Use keycloak_client_list first if you do not know the exact clientId. Returns a JSON object with uuid, clientId, enabled, and publicClient, or the text "Client not found." when no client matches.
Inputs: clientId (required).
keycloak_client_get_secretGet client secretARead-onlyIdempotent
Read the current secret of a confidential (non-public) realm client. Read-only and idempotent; it does not change the secret. By default the secret is returned masked; pass reveal=true to return the plaintext value. Use keycloak_client_get to confirm a client is confidential first, and keycloak_client_regenerate_secret to rotate it. Returns the (masked or plaintext) secret string, or "Client not found." when no client matches.
Inputs: clientId (required), reveal.
keycloak_client_listList clientsARead-onlyIdempotent
List all OAuth/OIDC clients registered in the configured Keycloak realm. Read-only and idempotent; it does not modify anything. Use this to discover clients before calling keycloak_client_get, keycloak_client_update, or keycloak_client_delete. Takes no parameters and returns a JSON array where each entry has uuid, clientId, enabled, and publicClient.
Inputs: no named parameters.
keycloak_client_mappers_listList client protocol mappersARead-onlyIdempotent
Lists the protocol mappers configured on a single client, aggregated across the client and its assigned scopes. This is a read-only, idempotent operation that does not modify Keycloak. Use it to inspect how tokens issued for the client are shaped; to first find a client's scopes use keycloak_client_default_scopes_get. Returns the protocol mappers as a JSON array, or the text "Client not found." when no client matches the given clientId.
Inputs: clientId (required).
keycloak_client_regenerate_secretRegenerate client secretADestructive
Regenerate (rotate) a confidential client's secret. This is a destructive, non-idempotent write: it invalidates the previous secret, which immediately stops working, so any system using the old value must be updated. Requires explicit confirmation via confirm=true (otherwise it aborts without changing anything). Use keycloak_client_get_secret to read the current secret without rotating. Returns the new plaintext secret, or a reason string when not regenerated.
Inputs: clientId (required), confirm.
keycloak_client_roles_listList client rolesARead-onlyIdempotent
Read-only: lists the client-level roles defined on a single Keycloak client (not realm roles). Use this to discover available client role names before assigning one with keycloak_user_client_role_assign; for realm-wide roles use keycloak_role_list instead. Returns a JSON array of roles (each with id, name, and description), or the message 'Client not found.' when no client matches the given ID.
Inputs: clientId (required).
keycloak_client_scope_assignAssign a default scope to a clientAIdempotent
Assigns an existing realm client scope to a client as a default scope. This is a write operation; it is idempotent, so re-assigning an already-assigned scope leaves the client unchanged. Use keycloak_client_scopes_list to find a valid scope name and keycloak_client_default_scopes_get to check current assignments before calling this. Returns a confirmation message when the scope is assigned, or a message starting with "Not assigned:" with the reason (for example when the client or scope does not exist).
Inputs: scope (required), clientId (required).
keycloak_client_scopes_listList client scopesARead-onlyIdempotent
Lists every client scope defined in the realm. This is a read-only, idempotent operation that takes no parameters and does not modify Keycloak. Use it to discover available scope names before calling keycloak_client_scope_assign or keycloak_client_scope_unassign. Returns a JSON array where each entry holds the scope's id, name, and protocol.
Inputs: no named parameters.
keycloak_client_scope_unassignRemove a default scope from a clientADestructive
Removes a default client scope from a client. This is a destructive write operation and is gated by an explicit confirmation step, so it does nothing unless confirm is true. It is not idempotent in effect: the first successful call detaches the scope, and a later call once the scope is gone reports that it was not removed. Use keycloak_client_default_scopes_get first to see which scopes are currently assigned. Returns a confirmation message when the scope is removed, or a message starting with "Not removed:" with the reason (for example missing confirmation, or an unknown client or scope).
Inputs: scope (required), clientId (required), confirm.
keycloak_client_updateUpdate clientAIdempotent
Update an existing client's enabled flag, public flag, redirect URIs and/or web origins. Only the fields you supply are changed; omitted fields are left untouched. This is a write operation and is idempotent: applying the same values again yields the same state. Use keycloak_client_list or keycloak_client_get to find the client first. Returns a confirmation message, or a reason string (e.g. when the client does not exist).
Inputs: clientId (required), enabled, webOrigins, publicClient, +1 more.
keycloak_events_adminList admin eventsARead-onlyIdempotent
Read-only. Returns recent administrative events from the realm's admin event log (such as CREATE, UPDATE, and DELETE operations on users, roles, clients, and configuration) as a JSON array. Use this to audit who changed what in the realm; for end-user authentication activity use keycloak_events_login instead. This tool is idempotent and never modifies Keycloak.
Inputs: max.
keycloak_events_loginList login eventsARead-onlyIdempotent
Read-only. Returns recent user login events from the realm's login event log (such as LOGIN, LOGIN_ERROR, and LOGOUT), as a JSON array ordered by the event log's default ordering. Use this to audit authentication activity or investigate failed logins; for administrative changes (user/role/config updates) use keycloak_events_admin instead. This tool is idempotent and never modifies Keycloak.
Inputs: max, type, user.
keycloak_federation_getGet a user federation providerARead-onlyIdempotent
Fetches a single user federation provider (such as LDAP or Kerberos) by its component id in the current realm. Read-only and idempotent; it does not modify any configuration. Use keycloak_federation_list first to obtain a valid id, then call this tool to inspect that specific provider. Returns a JSON object with the provider id, name, and providerId, or the text "Federation provider not found." when no provider matches the given id.
Inputs: id (required).
keycloak_federation_listList user federation providersARead-onlyIdempotent
Lists all user federation providers (such as LDAP or Kerberos) configured in the current realm. Read-only and idempotent; it does not modify any configuration. Use this to discover available providers and obtain their ids before calling keycloak_federation_get for details or keycloak_federation_sync to trigger a sync. Returns a JSON array where each entry contains the provider id, name, and providerId; an empty array means no providers are configured.
Inputs: no named parameters.
keycloak_federation_syncSynchronize a user federation providerA
Triggers a user synchronization from a user federation provider (such as LDAP) into the current realm. This is a write operation that imports or updates users; it is not destructive but is not idempotent, since each call re-runs the sync and the imported counts can differ between runs. Use keycloak_federation_list or keycloak_federation_get first to confirm the provider id, then run this to refresh users. Returns a JSON object describing the sync result reported by Keycloak.
Inputs: id (required), mode.
keycloak_group_createCreate groupA
Write operation. Creates a new top-level group in the realm with the given name. Not idempotent: calling it again with the same name creates or attempts another group rather than reusing one. Use keycloak_group_list afterward to obtain the new group's id. Returns a confirmation message containing the created group's name.
Inputs: name (required).
keycloak_group_deleteDelete groupADestructive
Destructive write operation that requires confirmation. Permanently deletes a group by its ID, including its membership and role assignments. This cannot be undone; find the ID with keycloak_group_list first. Returns a message confirming deletion, or, if confirmation was withheld, that it was not deleted with the reason.
Inputs: id (required), confirm.
keycloak_group_listList groupsARead-onlyIdempotent
Read-only. Lists the realm's top-level groups. Use this to discover group IDs and names before calling group write tools such as keycloak_group_member_add, keycloak_group_role_assign, or keycloak_group_delete. Idempotent and takes no parameters; returns a JSON array of objects, each with the group id, name, and path.
Inputs: no named parameters.
keycloak_group_member_addAdd group memberAIdempotent
Write operation. Adds an existing user to an existing group by their IDs. Idempotent: adding a user already in the group leaves membership unchanged. Resolve the IDs first with keycloak_group_list and a user listing tool; to undo, use keycloak_group_member_remove. Returns a fixed confirmation message.
Inputs: userId (required), groupId (required).
keycloak_group_member_removeRemove group memberADestructive
Destructive write operation that requires confirmation. Removes a user from a group by their IDs. Not idempotent in effect since it gates on confirmation; resolve IDs with keycloak_group_list and keycloak_group_members_list first, and use keycloak_group_member_add to reverse it. Returns a message stating the user was removed, or, if confirmation was withheld, that it was not removed with the reason.
Inputs: userId (required), groupId (required), confirm.
keycloak_group_members_listList group membersARead-onlyIdempotent
Read-only and idempotent. Lists the users that are direct members of the given group. Resolve the group ID first with keycloak_group_list. Returns a JSON array of user objects, each with id, username, email (or null), and enabled status.
Inputs: groupId (required).
keycloak_group_role_assignAssign a realm role to a groupAIdempotent
Write operation. Grants an existing realm role to a group, so the group's members inherit that role. Idempotent: re-assigning an already-granted role makes no further change. Resolve the group ID with keycloak_group_list and ensure the realm role exists beforehand. Returns a message stating the role was assigned, or, if it could not be, that it was not assigned with the reason.
Inputs: role (required), groupId (required).
keycloak_idp_createCreate identity providerA
Creates a new identity provider in the target realm. This is a write operation and is not idempotent: calling it again with an existing alias will fail rather than update. Check keycloak_idp_list first to avoid alias collisions, and use keycloak_idp_get afterward to verify the result. Returns a confirmation message naming the created provider.
Inputs: alias (required), providerId (required), config, enabled.
keycloak_idp_deleteDelete identity providerADestructive
Permanently deletes an identity provider from the target realm by its alias. This is a destructive write operation that requires confirmation: it proceeds only when confirm is true, otherwise it is skipped. It is not idempotent, since deleting an already-removed provider has no provider to remove. Use keycloak_idp_list or keycloak_idp_get first to confirm the alias. Returns a message stating whether the provider was deleted or, if not, the reason.
Inputs: alias (required), confirm.
keycloak_idp_getGet identity providerARead-onlyIdempotent
Fetches a single identity provider by its alias from the target realm. Read-only and idempotent; it makes no changes. Use it to inspect one provider after finding its alias with keycloak_idp_list. Returns a JSON object with alias, providerId, enabled, and displayName, or the text "Identity provider not found." if no provider matches the alias.
Inputs: alias (required).
keycloak_idp_listList identity providersARead-onlyIdempotent
Lists all identity providers configured in the target realm. Read-only and idempotent; it makes no changes. Use it to discover available providers before calling keycloak_idp_get, keycloak_idp_mappers_list, or keycloak_idp_delete. Takes no parameters and returns a JSON array of providers, each with alias, providerId, enabled, and displayName.
Inputs: no named parameters.
keycloak_idp_mappers_listList identity provider mappersARead-onlyIdempotent
Lists the mappers configured on a single identity provider, identified by its alias. Mappers control how claims and attributes from the external provider are mapped into Keycloak users. Read-only and idempotent; it makes no changes. Use it after keycloak_idp_list or keycloak_idp_get to inspect a provider's mappers. Returns a JSON array of mapper definitions.
Inputs: alias (required).
keycloak_realm_get_configGet realm configurationARead-onlyIdempotent
Read-only. Returns a curated subset of the realm's configuration as a JSON object, including realm name and enabled state, self-registration and password-reset flags, email verification and login-with-email settings, brute-force protection, the SSL requirement, and token and SSO session lifespans. Use this to inspect security-relevant realm settings without retrieving the full realm representation. Takes no parameters; it is idempotent and never modifies Keycloak.
Inputs: no named parameters.
keycloak_role_listList realm rolesARead-onlyIdempotent
Read-only: lists all realm-level roles defined in the Keycloak realm (not client roles). Takes no parameters. Use this to discover available realm role names before assigning one with keycloak_user_role_assign; for roles scoped to a specific client, use keycloak_client_roles_list instead. Returns a JSON array of roles, each with id, name, and description.
Inputs: no named parameters.
keycloak_server_infoGet server infoARead-onlyIdempotent
Read-only. Returns a small JSON summary of the connected Keycloak server, containing the 'keycloakVersion' field (the server version, or null when it cannot be determined). Use this for a quick connectivity and version check; for realm-specific settings use keycloak_realm_get_config instead. Takes no parameters; it is idempotent and never modifies Keycloak.
Inputs: no named parameters.
keycloak_user_client_role_assignAssign a client role to a userAIdempotent
Write: grants a single client-level role (belonging to one specific client) to a user, not a realm role. This is idempotent — assigning a role the user already has succeeds without changing anything. The role must already exist on the client; list candidates with keycloak_client_roles_list and verify current assignments with keycloak_user_client_roles_get. Returns a confirmation that the client role was assigned, or a message explaining why it was not (for example, the user, client, or role was not found).
Inputs: role (required), userId (required), clientId (required).
keycloak_user_client_roles_getGet a user's client rolesARead-onlyIdempotent
Read-only: lists the client-level roles assigned to a single user for one specific client (not realm roles). Use this to inspect a user's client role assignments before granting one with keycloak_user_client_role_assign or revoking one with keycloak_user_client_role_unassign; for realm-wide assignments use keycloak_user_roles_get. Returns a JSON array of roles (each with id, name, and description), or the message 'Client not found.' when no client matches the given ID.
Inputs: userId (required), clientId (required).
keycloak_user_client_role_unassignRemove a client role from a userADestructive
Destructive write: revokes a single client-level role (belonging to one specific client) from a user, removing the access that role grants; this is not a realm role. This action requires explicit confirmation and will not proceed unless 'confirm' is true. Use keycloak_user_client_roles_get first to see the user's current client roles; for realm-wide roles use keycloak_user_role_unassign instead. Returns a confirmation that the client role was removed, or a message explaining why it was not (for example, confirmation was declined or the user, client, or role was not found).
Inputs: role (required), userId (required), clientId (required), confirm.
keycloak_user_createCreate userA
Write operation that creates a new realm user and returns a confirmation message with the username. It does not set a password, so call keycloak_user_reset_password afterwards to give the account credentials; it also does not send any email. Not idempotent: calling it again with the same username creates a conflict rather than a duplicate. Use keycloak_user_update to change an existing user instead of recreating it.
Inputs: username (required), email, enabled, emailVerified.
keycloak_user_deleteDelete userADestructive
Destructive write that permanently removes a user from the realm, returning "User "" deleted." on success or a "Not deleted: " message otherwise. As a wrong-target guard, the supplied username must match the user that the id resolves to, and confirm must be true; otherwise the deletion is blocked. Look up the id and username with keycloak_user_get or keycloak_user_search first. Not reversible; consider keycloak_user_set_enabled to disable instead of deleting.
Inputs: id (required), username (required), confirm.
keycloak_user_getGet userARead-onlyIdempotent
Read-only. Fetches a single realm user by id and returns a JSON object with id, username, email and enabled flag, or the text "User not found." if no user has that id. Use keycloak_user_search first if you only know a username or email and need the id. Idempotent: repeated calls return the same result without changing anything.
Inputs: id (required).
keycloak_user_groups_listList a user's groupsARead-onlyIdempotent
Read-only and idempotent. Lists the groups the given user belongs to. Resolve the user ID first with a user listing tool. Returns a JSON array of group objects, each with id, name, and path.
Inputs: userId (required).
keycloak_user_logoutLog out userADestructive
Destructive write that revokes all active sessions for a user, forcing them to re-authenticate, and returns "User logged out." on success or a "Not logged out: " message if confirmation was declined. Requires explicit confirmation: pass confirm=true, otherwise the operation is blocked pending approval. The account itself stays enabled; use keycloak_user_set_enabled to block future logins or keycloak_user_sessions_list to inspect sessions first. Effectively idempotent: once sessions are revoked, a repeat call has nothing left to revoke.
Inputs: id (required), confirm.
keycloak_user_reset_passwordReset user passwordADestructive
Destructive write that overwrites a user's password with the supplied value, returning "Password reset." on success or a "Not reset: " message if confirmation was declined. Requires explicit confirmation: pass confirm=true, otherwise the operation is blocked pending approval. Commonly used right after keycloak_user_create to give a new account credentials. Not idempotent in effect, since it invalidates the previous password.
Inputs: id (required), password (required), confirm, temporary.
keycloak_user_role_assignAssign a realm role to a userAIdempotent
Write: grants a single realm-level role to a user (not a client role). This is idempotent — assigning a role the user already has succeeds without changing anything. The role must already exist in the realm; list candidates with keycloak_role_list and verify current assignments with keycloak_user_roles_get. Returns a confirmation that the role was assigned, or a message explaining why it was not (for example, the user or role was not found).
Inputs: role (required), userId (required).
keycloak_user_roles_getGet a user's realm rolesARead-onlyIdempotent
Read-only: lists the realm-level roles currently assigned to a single user (not client roles). Use this to inspect a user's realm role assignments before granting one with keycloak_user_role_assign or revoking one with keycloak_user_role_unassign; for client-scoped assignments use keycloak_user_client_roles_get. Returns a JSON array of roles, each with id, name, and description.
Inputs: userId (required).
keycloak_user_role_unassignRemove a realm role from a userADestructive
Destructive write: revokes a single realm-level role from a user (not a client role), removing the access that role grants. This action requires explicit confirmation and will not proceed unless 'confirm' is true. Use keycloak_user_roles_get first to see the user's current realm roles; for client-scoped roles use keycloak_user_client_role_unassign instead. Returns a confirmation that the role was removed, or a message explaining why it was not (for example, confirmation was declined or the user or role was not found).
Inputs: role (required), userId (required), confirm.
keycloak_user_searchSearch usersARead-onlyIdempotent
Read-only. Searches users in the configured realm and returns a JSON array of matches, each with id, username, email and enabled flag. Use this to discover a user's id before calling id-based tools such as keycloak_user_get, keycloak_user_update or keycloak_user_delete. All filters are optional and combined; with no filters it returns the first page of users. Results are paginated and capped at 500 per call.
Inputs: max, email, first, search, +1 more.
keycloak_user_send_action_emailSend action emailA
Write operation that emails the user a link prompting them to complete one or more required actions (such as verifying their email or updating their password), and returns a confirmation message. The user must have a valid email address configured. Not idempotent: each call sends a fresh email. Use this for self-service flows; to set a password directly without involving the user, use keycloak_user_reset_password instead.
Inputs: id (required), actions (required).
keycloak_user_sessions_listList user sessionsARead-onlyIdempotent
Read-only. Returns a JSON array of a user's currently active sessions (an empty array if none). Use it to inspect where a user is logged in before deciding whether to revoke access with keycloak_user_logout. Idempotent: it never changes any state and repeated calls reflect only sessions that are still active.
Inputs: id (required).
keycloak_user_set_enabledEnable or disable userAIdempotent
Write operation that enables or disables a single user account by id, returning a confirmation message. Disabling blocks the user from logging in but does not delete the account or revoke existing sessions; use keycloak_user_logout to terminate active sessions, or keycloak_user_delete to remove the account. Idempotent: setting the same enabled value repeatedly leaves the account in the same state.
Inputs: id (required), enabled (required).
keycloak_user_updateUpdate userAIdempotent
Write operation that updates an existing user's profile fields and returns a confirmation message. Only the fields you supply are changed; omitted fields are left untouched (no field is cleared by omission). Idempotent: applying the same values again leaves the user unchanged. Use keycloak_user_get first to read current values, and keycloak_user_reset_password for credentials rather than this tool.
Inputs: id (required), email, enabled, lastName, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 56 tools
Every tool targets a distinct Keycloak resource/action combination, and the descriptions explicitly cross-reference related tools (e.g., realm vs. client roles, login vs. admin events, client scopes catalog vs. assigned scopes). Even the similar role-assignment tools are clearly separated by realm/client and user/group scope.
Tool names consistently follow the keycloak_<resource>_<verb> pattern, using predictable verbs like list, get, create, update, delete, assign, and unassign. Minor deviations such as keycloak_user_search and keycloak_server_info, plus occasional _list vs. _get for collections, prevent a perfect score.
At 56 tools, the set is far beyond the typical 3-15 tool sweet spot and crosses the 50+ threshold for an extreme count. Although the Keycloak domain is broad, this many entry points create significant agent selection overhead and suggest over-decomposition of the API surface.
User and client lifecycle CRUD is well covered, and there is broad read-only coverage of roles, scopes, mappers, auth flows, authz, and federation. However, these latter areas largely lack create/update/delete tools, and group role grants cannot be revoked (no group_role_unassign), so common admin workflows dead-end.
Maintenance
Related MCP Connectors
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
Keycloak identity management expert with semantic search, protocol guides, and config analysis
Manage API keys, identities, permissions, rate-limit overrides and verification analytics.
Manage remote servers, SSH terminals, files, databases and proxies with scoped access and approvals.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables management of Keycloak identity and access management through the Keycloak Admin REST API, providing 299 tools for operations like user management, client configuration, and realm administration via natural language.1003MIT
- AlicenseNot gradedqualityCmaintenanceExposes Keycloak admin operations as tools via the Model Context Protocol, allowing management of users, clients, groups, roles, and more through natural language.ISC
- AlicenseNot gradedqualityDmaintenanceEnables administration of Keycloak identity and access management through MCP, allowing management of realms, clients, users, roles, groups, identity providers, and sessions from any MCP client.Apache 2.0
- AlicenseAqualityBmaintenanceEnables MCP-capable clients to inspect and manage Keycloak realms, users, clients, roles, and groups with layered security modes, realm allowlisting, protected realms, delete gating, dry-run, and audit logging.855 npm1MIT