keycloak-mcp-server

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.

Install

npm install
npm run build

Configure

The server talks to the Keycloak Admin REST API. Provide credentials via environment variables (see .env.example):

Variable	Default	Notes
KEYCLOAK_URL	http://localhost:8081	Base URL
KEYCLOAK_REALM	master	Auth realm (master can administer all realms)
KEYCLOAK_CLIENT_ID	admin-cli	Client used for the grant
KEYCLOAK_ADMIN_USER / KEYCLOAK_ADMIN_PASSWORD	admin / admin	Password grant
KEYCLOAK_CLIENT_SECRET	—	If set, uses a client-credentials (service account) grant instead
KEYCLOAK_MCP_READONLY	—	Set true/1 to refuse all write tools
KEYCLOAK_MCP_HTTP_PORT	—	If set, serve remote Streamable HTTP at :PORT/mcp instead of stdio

Use with Claude Code

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=admin

Tools

111 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.

<details> <summary>Full tool catalog (111)</summary>

Core reads (10)

Tool	Description
kc_list_realms	List all realms (name + enabled flag).
kc_get_realm	Get a realm's configuration summary.
kc_list_clients	List OAuth clients in a realm.
kc_get_client	Get a client by its clientId.
kc_list_client_scopes	List client scopes in a realm.
kc_list_users	List users in a realm (paged).
kc_get_user	Get a single user by id or (exact) username.
kc_list_roles	List realm roles.
kc_list_groups	List groups in a realm.
kc_list_identity_providers	List identity providers (SSO / social login) in a realm.

Users — core writes (5)

Tool	Description
kc_create_user	Create a user in a realm (optionally set an initial password).
kc_set_user_enabled	Enable or disable a user.
kc_assign_realm_role	Assign a realm role to a user.
kc_remove_realm_role	Remove a realm role from a user.
kc_delete_user	Delete a user (destructive). Dry-run unless confirm=true.

Users — lifecycle & roles (12)

Tool	Description
kc_update_user	Update a user's profile fields; attributes are merged into existing ones.
kc_count_users	Count users in a realm, optionally filtered.
kc_get_user_sessions	List a user's active sessions.
kc_logout_user	Log a user out of ALL sessions (destructive). Dry-run unless confirm=true.
kc_reset_user_password	Set a user's password (temporary=true forces change on next login).
kc_send_verify_email	Send the email-verification email to a user.
kc_execute_actions_email	Email a user a link to perform required actions (e.g. UPDATE_PASSWORD, CONFIGURE_TOTP).
kc_remove_user_from_group	Remove a user from a group.
kc_list_user_groups	List the groups a user belongs to.
kc_list_user_role_mappings	List a user's realm-role and client-role mappings.
kc_assign_client_role	Assign a client role to a user (client resolved by clientId, role by name).
kc_remove_client_role	Remove a client role from a user (client resolved by clientId, role by name).

Clients — full management (12)

Tool	Description
kc_update_client	Update a client (merge: only provided fields change).
kc_get_client_secret	Get the current secret of a confidential client.
kc_regenerate_client_secret	Rotate a client's secret (destructive: old secret stops working). Dry-run unless confirm=true.
kc_get_service_account_user	Get the service-account user of a client (serviceAccountsEnabled).
kc_add_default_client_scope	Attach a client scope (by name) as a DEFAULT scope of a client.
kc_remove_default_client_scope	Detach a DEFAULT client scope (by name) from a client.
kc_add_optional_client_scope	Attach a client scope (by name) as an OPTIONAL scope of a client.
kc_remove_optional_client_scope	Detach an OPTIONAL client scope (by name) from a client.
kc_list_client_protocol_mappers	List protocol mappers of a client.
kc_create_client_protocol_mapper	Create a protocol mapper on a client (config passed through as-is).
kc_delete_client_protocol_mapper	Delete a protocol mapper (by name) from a client (destructive). Dry-run unless confirm=true.
kc_list_client_roles	List roles defined on a client.

Clients / roles / groups / scopes — core writes (9)

Tool	Description
kc_create_client	Create an OIDC client in a realm.
kc_delete_client	Delete a client by clientId (destructive). Dry-run unless confirm=true.
kc_create_realm_role	Create a realm role.
kc_delete_realm_role	Delete a realm role by name (destructive). Dry-run unless confirm=true.
kc_create_group	Create a group in a realm.
kc_delete_group	Delete a group by id (destructive). Dry-run unless confirm=true.
kc_add_user_to_group	Add a user to a group.
kc_create_client_scope	Create a client scope.
kc_delete_client_scope	Delete a client scope by id (destructive). Dry-run unless confirm=true.

Realms (9)

Tool	Description
kc_create_realm	Create a new realm.
kc_update_realm	Update realm settings (partial RealmRepresentation passthrough).
kc_delete_realm	Delete a realm and everything in it (destructive). Dry-run unless confirm=true.
kc_get_realm_events_config	Get a realm's login/admin event logging configuration.
kc_update_realm_events_config	Update a realm's event logging config (only provided fields change).
kc_clear_realm_cache	Clear the server-side realm cache (destructive-ish). Dry-run unless confirm=true.
kc_clear_user_cache	Clear the server-side user cache (destructive-ish). Dry-run unless confirm=true.
kc_get_realm_keys	List a realm's active key metadata (no key material blobs).
kc_get_server_info	Get Keycloak server info (version, features, themes).

Roles — composites & client roles (8)

Tool	Description
kc_update_realm_role	Update a realm role's description.
kc_get_role_composites	List the composite (child) roles of a realm role.
kc_add_role_composites	Add realm roles (by name) as composites of a realm role.
kc_remove_role_composites	Remove composite roles (by name) from a realm role (destructive). Dry-run unless confirm=true.
kc_list_role_users	List users holding a realm role.
kc_create_client_role	Create a role on a client (resolved by clientId).
kc_update_client_role	Update a client role's description (client resolved by clientId).
kc_delete_client_role	Delete a client role (destructive; client resolved by clientId). Dry-run unless confirm=true.

Groups — members & mappings (7)

Tool	Description
kc_get_group	Get a single group by id, including its direct subgroups.
kc_update_group	Update a group's name and/or attributes.
kc_list_group_members	List members of a group (paged).
kc_create_child_group	Create a child group under a parent group.
kc_add_group_realm_role	Map a realm role onto a group (members inherit it).
kc_remove_group_realm_role	Remove a realm-role mapping from a group (destructive). Dry-run unless confirm=true.
kc_list_group_role_mappings	List a group's role mappings (realm + client roles).

Client scopes — mappers & realm defaults (8)

Tool	Description
kc_get_client_scope	Get a client scope by id or name (includes protocol mappers).
kc_update_client_scope	Update a client scope's name/description/protocol/attributes (locate by scopeId or name).
kc_list_scope_protocol_mappers	List protocol mappers on a client scope.
kc_create_scope_protocol_mapper	Add a protocol mapper to a client scope.
kc_delete_scope_protocol_mapper	Delete a protocol mapper from a client scope (destructive). Dry-run unless confirm=true.
kc_list_realm_default_client_scopes	List the realm's default and/or optional client scopes (assigned to new clients).
kc_add_realm_default_client_scope	Add a client scope to the realm's default or optional list (locate by scopeId or name).
kc_remove_realm_default_client_scope	Remove a client scope from the realm's default or optional list (destructive). Dry-run unless confirm=true.

Identity providers (7)

Tool	Description
kc_get_idp	Get a single identity provider by alias (clientSecret masked).
kc_create_idp	Create an identity provider (e.g. oidc, saml, google, github).
kc_update_idp	Update an identity provider; config keys are merged into the existing config.
kc_delete_idp	Delete an identity provider by alias (destructive). Dry-run unless confirm=true.
kc_list_idp_mappers	List mappers of an identity provider.
kc_create_idp_mapper	Create a mapper on an identity provider.
kc_delete_idp_mapper	Delete an identity-provider mapper by id (destructive). Dry-run unless confirm=true.

Sessions, events & brute-force (7)

Tool	Description
kc_list_admin_events	List admin (audit) events with optional operation/resource/date filters.
kc_list_login_events	List user (login) events with optional type/user/date filters.
kc_clear_admin_events	Clear ALL admin (audit) events in a realm (destructive). Dry-run unless confirm=true.
kc_clear_login_events	Clear ALL user (login) events in a realm (destructive). Dry-run unless confirm=true.
kc_get_client_session_stats	Active/offline session counts per client in a realm.
kc_get_brute_force_status	Brute-force (attack detection) lockout status for a user.
kc_clear_brute_force	Clear brute-force lockout for one user (userId) or ALL users (destructive). Dry-run unless confirm=true.

Authentication flows (7)

Tool	Description
kc_list_auth_flows	List authentication flows in a realm.
kc_get_flow_executions	List the executions of an authentication flow by flow alias.
kc_list_required_actions	List required actions registered in a realm.
kc_update_required_action	Update a required action by alias (merge: only provided fields change).
kc_lower_required_action_priority	Move a required action one position down in the priority order.
kc_copy_auth_flow	Copy an authentication flow (by source alias) to a new flow name.
kc_delete_auth_flow	Delete a non-built-in authentication flow by id (destructive). Dry-run unless confirm=true.

Organizations & components (10)

Tool	Description
kc_list_organizations	List organizations in a realm, optionally filtered by search text.
kc_get_organization	Get one organization by id.
kc_create_organization	Create an organization with a name and one or more email domains.
kc_delete_organization	Delete an organization by id (destructive). Dry-run unless confirm=true.
kc_list_org_members	List members of an organization.
kc_add_org_member	Add an existing realm user to an organization.
kc_remove_org_member	Remove a user from an organization (destructive). Dry-run unless confirm=true.
kc_list_components	List realm components (user federation, key providers), filterable by provider type.
kc_get_component	Get one component by id, including its config.
kc_delete_component	Delete a component by id (destructive). Dry-run unless confirm=true.

</details>

Roadmap

• Remote auth: the Streamable HTTP mode has no auth gate yet — put OAuth2/bearer in front before exposing it beyond localhost.
• Credential flows: BCrypt hash-import for app migrations.

License

Apache-2.0