Keycloak Admin

io.github.mrz1880Published by GitHub account mrz1880v0.2.3Updated Oct 24, 2026

Administer Keycloak via its Admin REST API: users, roles, clients, groups, IdP, events.

VerifiedSTDIODesktop onlyCloud & Infrastructure Security & Monitoring

Server details

Identifier: io.github.mrz1880/mcp-keycloak-admin
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account mrz1880 for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.mrz1880%2Fmcp-keycloak-admin.svg)](https://sourceweft.com/mcp/io.github.mrz1880%2Fmcp-keycloak-admin?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Local MCP server that lets an assistant administer a Keycloak 26.x realm through its Admin REST API: users, roles, clients, groups, IdPs and events.

What you can do: Search, read, create, update, enable/disable and delete realm users, list their sessions, send action emails, reset passwords and revoke sessions
List, assign and revoke realm roles and client roles for users and groups
List, create, update and delete clients, read or regenerate client secrets, and manage default scopes and protocol mappers
List, create and delete groups, add or remove members, and grant roles to groups
List, create and delete identity providers and their mappers, list user federation providers and trigger syncs
Read authentication flows, required actions, authorization resources, policies and permissions, login and admin events, realm config and server version
When to use it: Useful when an assistant or IDE agent needs to do routine Keycloak administration — looking up users, managing roles, clients and groups, or reading events — without handing over the raw admin console. Best for teams that want guardrails such as read-only mode and realm allow-lists around those operations.
Requirements: Node.js 20 or newer and a reachable Keycloak 26.x server. Required environment variables: KEYCLOAK_BASE_URL, KEYCLOAK_REALM and AUTH_MODE. In service_account mode, KC_CLIENT_ID and KC_CLIENT_SECRET; in password mode, KC_ADMIN_USERNAME and KC_ADMIN_PASSWORD, with optional KC_ADMIN_REALM. Optional READ_ONLY and ALLOWED_REALMS. Runs locally over stdio, typically via npx.

Before you install

The server holds admin credentials: KC_CLIENT_SECRET or KC_ADMIN_PASSWORD, which grant broad control of the realm. Write and destructive tools change real data — deleting users, clients, groups and IdPs, resetting passwords, revoking sessions, regenerating client secrets (the old secret stops working) and triggering federation syncs. Destructive tools ask for confirmation, but set READ_ONLY and ALLOWED_REALMS, especially for production, and grant the client least-privilege roles.

Installation

In SourceWeft

Open Keycloak Admin in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-keycloak-admin

[npm version] [CI] [CodeQL] [License: MIT]

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:

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

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 — the admin-cli client with an admin username/password.
Safe by default:
- READ_ONLY mode hides every write/destructive tool.
- ALLOWED_REALMS restricts which realms the server may operate on.
- Destructive operations require explicit confirmation (native MCP elicitation, with a confirm: true parameter 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:

json

{  "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"      }    }  }}

{  "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:

json

{  "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"      }    }  }}

{  "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
`KEYCLOAK_BASE_URL`	yes	Base URL of the Keycloak server (no trailing slash).
`KEYCLOAK_REALM`	yes	Realm the server operates on.
`AUTH_MODE`	yes	`service_account` or `password`.
`KC_CLIENT_ID`	if `service_account`	Confidential client id (e.g. `mcp-admin`).
`KC_CLIENT_SECRET`	if `service_account`	Client secret.
`KC_ADMIN_USERNAME`	if `password`	Admin username.
`KC_ADMIN_PASSWORD`	if `password`	Admin password.
`KC_ADMIN_REALM`	no (default `master`)	Realm holding the admin user (`password` mode).
`READ_ONLY`	no (default `false`)	When `true`, write/destructive tools are not registered.
`ALLOWED_REALMS`	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 main branch, which can run ahead of the latest npm release shown by the version badge above. To confirm what's available in your install, check npm view mcp-keycloak-admin version and pin mcp-keycloak-admin@latest.

Tool	Level	Description
`keycloak_user_search`	R	Search realm users by email, username or free text.
`keycloak_user_get`	R	Fetch a single user by id.
`keycloak_user_sessions_list`	R	List a user's active sessions.
`keycloak_user_create`	W	Create a realm user.
`keycloak_user_update`	W	Update a user's email, name or enabled flag.
`keycloak_user_set_enabled`	W	Enable or disable a user.
`keycloak_user_send_action_email`	W	Send a required-actions email.
`keycloak_user_reset_password`	D	Set a new password for a user.
`keycloak_user_logout`	D	Revoke all of a user's sessions.
`keycloak_user_delete`	D	Permanently delete a user (id + username must match).
`keycloak_role_list`	R	List realm roles.
`keycloak_user_roles_get`	R	List a user's realm roles.
`keycloak_user_role_assign`	W	Grant a realm role to a user.
`keycloak_user_role_unassign`	D	Revoke a realm role from a user.
`keycloak_client_roles_list`	R	List the roles defined on a client.
`keycloak_user_client_roles_get`	R	List a user's client roles.
`keycloak_user_client_role_assign`	W	Grant a client role to a user.
`keycloak_user_client_role_unassign`	D	Revoke a client role from a user.
`keycloak_client_list`	R	List the realm clients.
`keycloak_client_create`	W	Create a realm client.
`keycloak_client_update`	W	Update a client (enabled, public, redirect URIs, CORS web origins).
`keycloak_client_delete`	D	Delete a client.
`keycloak_client_get`	R	Fetch a client by its clientId.
`keycloak_client_get_secret`	R	Read a client secret (masked unless `reveal`).
`keycloak_client_scopes_list`	R	List the realm's client scopes.
`keycloak_client_default_scopes_get`	R	List a client's default scopes.
`keycloak_client_mappers_list`	R	List a client's protocol mappers.
`keycloak_client_scope_assign`	W	Add a default scope to a client.
`keycloak_client_scope_unassign`	D	Remove a default scope from a client.
`keycloak_client_regenerate_secret`	D	Regenerate a client secret (old one stops working).
`keycloak_group_list`	R	List the realm's top-level groups.
`keycloak_group_members_list`	R	List the members of a group.
`keycloak_user_groups_list`	R	List the groups a user belongs to.
`keycloak_group_create`	W	Create a top-level group.
`keycloak_group_member_add`	W	Add a user to a group.
`keycloak_group_role_assign`	W	Grant a realm role to a group.
`keycloak_group_member_remove`	D	Remove a user from a group.
`keycloak_group_delete`	D	Delete a group.
`keycloak_idp_list`	R	List identity providers.
`keycloak_idp_get`	R	Fetch an identity provider by alias.
`keycloak_idp_mappers_list`	R	List an identity provider's mappers.
`keycloak_idp_create`	W	Create an identity provider.
`keycloak_idp_delete`	D	Delete an identity provider.
`keycloak_federation_list`	R	List user federation (LDAP/Kerberos) providers.
`keycloak_federation_get`	R	Fetch a federation provider by id.
`keycloak_federation_sync`	W	Trigger a user sync (full or changed).
`keycloak_auth_flows_list`	R	List authentication flows.
`keycloak_auth_required_actions_list`	R	List required actions.
`keycloak_auth_required_action_set_enabled`	W	Enable/disable a required action.
`keycloak_authz_resources_list`	R	List a client's authorization resources.
`keycloak_authz_policies_list`	R	List a client's authorization policies.
`keycloak_authz_permissions_list`	R	List a client's authorization permissions.
`keycloak_events_login`	R	Read recent login events (filterable).
`keycloak_events_admin`	R	Read recent admin events.
`keycloak_realm_get_config`	R	Read key realm configuration flags.
`keycloak_server_info`	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

bash

npm installnpm test              # unit testsnpm run test:integration  # spins up a real Keycloak 26 via Testcontainers (needs Docker)npm run check         # typecheck + lint + format check + unit testsnpm run build         # bundle to dist/

npm installnpm test              # unit testsnpm run test:integration  # spins up a real Keycloak 26 via Testcontainers (needs Docker)npm run check         # typecheck + lint + format check + unit testsnpm run build         # bundle to dist/

Releases are automated — see docs/releasing.md.

Contributing

Contributions are welcome — please read CONTRIBUTING.md.

License

MIT

Source: README.md at commit 8f97751

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v0.2.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts