Keycloak Admin
Administer Keycloak via its Admin REST API: users, roles, clients, groups, IdP, events.
Open source Open in the app JSON README (API)
About
Administer Keycloak via its Admin REST API: users, roles, clients, groups, IdP, events.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- mrz1880
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.3
- Stars
- 1
- Open pull requests
- 4
- Last push
- 2026-09-03T09:16:10Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:51
- Updated
- 2026-08-29 04:00:51
- Origin id
io.github.mrz1880/mcp-keycloak-admin
README
# mcp-keycloak-admin
[](https://www.npmjs.com/package/mcp-keycloak-admin)
[](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/ci.yml)
[](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/codeql.yml)
[](LICENSE)
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server to
administer a [Keycloak](https://www.keycloak.org) 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`:
```bash
npx -y mcp-keycloak-admin
```
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](#usage-with-an-mcp-client).
New to it? The [Quickstart](docs/quickstart.md) 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"
}
}
}
}
```
See [docs/setup-keycloak.md](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"
}
}
}
}
```
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`](.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/users.md), [docs/roles.md](docs/roles.md),
[docs/clients.md](docs/clients.md), [docs/groups.md](docs/groups.md) and
[docs/events-realm.md](docs/events-realm.md) for parameters and examples, and
[docs/security.md](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](docs/development.md)
for how to add one.
## Development
```bash
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](docs/releasing.md).
## Contributing
Contributions are welcome — please read [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[MIT](LICENSE)