Keycloak MCP Server
by ZakariaDani
README.md
# Keycloak MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes
[Keycloak](https://www.keycloak.org/) admin operations as tools. It runs over **stdio**
and is launched by an MCP client (Claude Desktop, Claude Code, the MCP Inspector, etc.).
It covers day-to-day administration across users, roles (including composite roles), groups,
clients, client scopes and protocol mappers, realms and realm settings, identity providers,
authentication flows, authorization services, organizations, LDAP/AD user federation, events
and realm import/export: over 100 tools in 13 groups. Load only
the groups you need with the [`KEYCLOAK_TOOLS`](#tool-groups) environment variable.
Built on [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
and [`@keycloak/keycloak-admin-client`](https://github.com/keycloak/keycloak-nodejs-admin-client).
---
## Table of Contents
- [How it works](#how-it-works)
- [Requirements](#requirements)
- [Environment variables](#environment-variables)
- [Tool groups](#tool-groups)
- [Keycloak setup (service account)](#keycloak-setup-service-account)
- [Install & run](#install--run)
- [Integrate with Claude](#integrate-with-claude)
- [Claude Code (CLI)](#claude-code-cli)
- [Claude Desktop](#claude-desktop)
- [MCP Inspector](#mcp-inspector)
- [Tools reference](#tools-reference)
- [Usage tips](#usage-tips)
- [Troubleshooting](#troubleshooting)
---
## How it works
- The server authenticates to Keycloak using the **client_credentials** grant (a service
account) — no username/password required.
- A single shared `KeycloakAdminClient` is kept alive with lazy token management: the token
is re-fetched only when it is within ~10s of expiry.
- Every tool takes a **`realm`** argument identifying which realm the operation targets.
This is distinct from `KEYCLOAK_REALM`, which is only the realm used to *authenticate* the
admin service account.
- Users are addressed by **username**, clients by **clientId**, groups by **path or name**,
and roles by **name** — no UUIDs required in tool arguments.
- All diagnostic logging goes to **stderr**; **stdout** is reserved for the MCP protocol.
---
## Requirements
- **Node.js 18+** (Node 22 recommended)
- A running **Keycloak** instance (v26.x tested)
- A confidential client with a **service account** that has admin roles (see below)
---
## Environment variables
Loaded from a `.env` file at the project root.
| Variable | Required | Default | Description |
| ------------------------ | -------- | ------------------------- | -------------------------------------------------------------------------------------------- |
| `KEYCLOAK_BASE_URL` | no | `http://localhost:8080` | Base URL of the Keycloak server. |
| `KEYCLOAK_REALM` | no | `master` | Realm used for **admin authentication** (where the service-account client lives). Not the target realm of operations. |
| `KEYCLOAK_CLIENT_ID` | **yes** | — | The confidential client's `clientId` used for the client_credentials grant. |
| `KEYCLOAK_CLIENT_SECRET` | **yes** | — | The service account client secret. **Keep this out of version control.** |
| `KEYCLOAK_FILES_DIR` | no | any location | Directory the realm import/export tools may read from and write to. When set, any other path is refused (symlinks are resolved first). Recommended. |
| `KEYCLOAK_TOOLS` | no | all groups | Comma-separated [tool groups](#tool-groups) to expose, e.g. `users,roles`. See below. |
Example `.env`:
```dotenv
KEYCLOAK_BASE_URL=http://localhost:8080
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=keycloak-mcp
KEYCLOAK_CLIENT_SECRET=your-service-account-secret
KEYCLOAK_TOOLS=users,roles,groups
```
### Tool groups
With every group enabled the server exposes over 100 tools, and an MCP client loads all of
their descriptions into the model's context. `KEYCLOAK_TOOLS` limits that to the groups you
need. Unset, empty or `all` exposes everything. Names are case-insensitive; an unknown name
stops the server at startup with a message listing the valid groups.
| Group | Tools |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `users` | User read/write: profile, credentials, sessions, password, logout, impersonate, unlock. |
| `roles` | Realm and client roles, role mappings on users, composite roles. |
| `groups` | Groups and group membership. |
| `clients` | Clients, secrets, client service-account user. |
| `client-scopes` | Client scopes, assigning them to clients, and protocol mappers (on clients and scopes). |
| `realms` | Realm create/delete/enable, settings, SMTP, event-storage config. |
| `identity-providers` | Identity providers and their mappers. |
| `authentication` | Authentication flows, flow bindings and required actions. |
| `authorization` | Authorization services: resources, scopes, policies, permissions, evaluation. |
| `organizations` | Organizations (B2B tenants): members, invitations, linked identity providers. |
| `import-export` | Realm export to JSON, and import into an existing or new realm. |
| `federation` | LDAP/AD user federation: providers, sync, mappers. |
| `events` | Login events and admin events. |
Each tool belongs to exactly one group. The startup line on stderr reports what was loaded,
e.g. `keycloak-mcp: 32 tools registered (groups: users, roles)`.
A group only hides tools from the model; it is not a security boundary. What the server can
actually do is still limited by the roles on the service account (see
[Keycloak setup](#keycloak-setup-service-account)). For a read-only deployment, grant only
view roles.
Set it in `.env`, or per client in the MCP config, e.g. for Claude Code:
```bash
claude mcp add keycloak -e KEYCLOAK_TOOLS=users,roles -- <command...>
```
> ⚠️ Add `.env` to `.gitignore`. The secret is a full admin credential.
---
## Keycloak setup (service account)
1. In the realm that will **authenticate** the server (usually `master`), create a client
(e.g. `keycloak-mcp`):
- **Client authentication**: On (confidential)
- **Service accounts roles**: Enabled
- Standard/Direct-access flows can be off.
2. Copy the client secret from **Credentials** into `KEYCLOAK_CLIENT_SECRET`.
3. Grant the service account admin roles under **Service account roles**:
- For full access: assign the `admin` role (or `realm-admin` from the `realm-management`
client of each target realm).
- For read-only usage: assign roles like `view-users`, `view-clients`, `view-realm`,
`query-users`, `query-clients`.
- Write tools (create/update/delete user, reset password, assign roles, group
membership, send email, logout) additionally need `manage-users` and `manage-clients`.
- Realm-level writes (`set-realm-enabled`, `update-realm-settings`, `update-realm-smtp`,
`update-realm-events-config`, `create-realm-role`, `delete-realm-role`, `create-group`,
`delete-group`) need `manage-realm`.
- The authentication-flow and required-action tools need `view-realm` (read) or
`manage-realm` (create/copy/delete/edit flows, `set-realm-flow-binding`,
`update-required-action`).
- The authorization tools need `view-authorization` (read, `evaluate-authorization`,
`export-authorization-settings`) or `manage-authorization` (create/update/delete), plus
`view-users` / `view-clients` where a policy names users or clients.
- `export-realm` needs `view-realm` (plus `view-clients` / `view-users`-level access for what it
includes). `partial-import-realm` needs the manage roles of the types it imports
(`manage-users`, `manage-clients`, `manage-realm`), and `import-realm` needs the global
`create-realm` role, so the service account must authenticate in the master realm.
- The organization tools need `view-realm` (read) or `manage-realm` (create/update/delete,
members, invitations, identity-provider links), plus `manage-users` to add or remove members.
They only work once `organizationsEnabled` is on for the realm.
- The user-federation tools need `view-realm` (read) or `manage-realm` (create, update,
delete, sync, unlink, mappers). `unlink-federated-users` and
`remove-imported-federated-users` also touch users, so grant `manage-users` too.
- `create-realm` and `delete-realm` need the `create-realm` role (or global `admin`) in the
master realm; they act across realms, so the service account must authenticate there.
- `impersonate-user` needs the `impersonation` role. `create-client` /
`update-client` / `delete-client` / `regenerate-client-secret` and the client-role
tools need `manage-clients`.
- `unlock-user` needs `manage-users`. `list-events` / `list-admin-events` need
`view-events`. The identity-provider tools need `view-identity-providers` (read) or
`manage-identity-providers` (create/update/delete). Protocol-mapper and client-scope
tools need `manage-clients`.
---
## Install & run
```bash
npm install
npm run dev # Run the server over stdio, loading .env
npm run inspect # Launch the MCP Inspector against the server for interactive testing
```
`npm run dev` runs the TypeScript entry point directly via `tsx --env-file=.env src/index.ts`.
There is no separate build step.
---
## Integrate with Claude
### Claude Code (CLI)
The simplest, self-contained registration points the project's local `tsx` binary at the
entry file and loads secrets from `.env` (so no secrets appear on the command line):
```bash
# From the project root
P="$(pwd)"
claude mcp add keycloak --scope user -- \
"$P/node_modules/.bin/tsx" --env-file="$P/.env" "$P/src/index.ts"
```
Verify it connected:
```bash
claude mcp list
# keycloak: .../tsx --env-file=.../.env .../src/index.ts - ✔ Connected
```
Prefer passing env vars explicitly instead of an `.env` file? Use `--env` flags:
```bash
P="$(pwd)"
claude mcp add keycloak --scope user \
--env KEYCLOAK_BASE_URL=http://localhost:8080 \
--env KEYCLOAK_REALM=master \
--env KEYCLOAK_CLIENT_ID=keycloak-mcp \
--env KEYCLOAK_CLIENT_SECRET=your-service-account-secret \
-- "$P/node_modules/.bin/tsx" "$P/src/index.ts"
```
To remove it later: `claude mcp remove keycloak`.
### Claude Desktop
Edit the MCP config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Add a `keycloak` entry under `mcpServers` (use **absolute paths**):
```json
{
"mcpServers": {
"keycloak": {
"command": "/absolute/path/to/keycloak-mcp/node_modules/.bin/tsx",
"args": [
"--env-file=/absolute/path/to/keycloak-mcp/.env",
"/absolute/path/to/keycloak-mcp/src/index.ts"
]
}
}
}
```
Or pass credentials inline via `env` instead of `--env-file`:
```json
{
"mcpServers": {
"keycloak": {
"command": "/absolute/path/to/keycloak-mcp/node_modules/.bin/tsx",
"args": ["/absolute/path/to/keycloak-mcp/src/index.ts"],
"env": {
"KEYCLOAK_BASE_URL": "http://localhost:8080",
"KEYCLOAK_REALM": "master",
"KEYCLOAK_CLIENT_ID": "keycloak-mcp",
"KEYCLOAK_CLIENT_SECRET": "your-service-account-secret"
}
}
}
}
```
Restart Claude Desktop. The Keycloak tools then appear in the tools (🔨) menu.
### MCP Inspector
```bash
npm run inspect
```
Opens the Inspector UI where you can browse and invoke each tool interactively.
---
## Tools reference
All tools take a `realm` argument (the target realm) unless noted. Identifiers are
**human-readable**: users by `username`, clients by `clientId`, groups by path/name, roles
by name. List tools support `first`/`max` pagination (default `first=0`, `max=50`, max `200`).
The tools are organised in the same groups as `KEYCLOAK_TOOLS` (see [Tool groups](#tool-groups)),
so you can see exactly what each group exposes. A tool is only available when its group is enabled.
### Users (`users`, 17 tools)
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-users` | List users (id, username, email, enabled, federation link). | `realm`, `search?`, `first?`, `max?` |
| `get-user` | Get a single user by username, with profile fields and attributes. Optionally include groups and realm roles. | `realm`, `username`, `includeGroups?`, `includeRealmRoles?` |
| `count-users` | Count users, optionally matching a search term. Handy before paginating. | `realm`, `search?` |
| `list-user-groups` | List the groups a user is a direct member of (id, name, path). | `realm`, `username` |
| `list-user-roles` | List a user's directly-assigned role mappings: realm roles plus client roles grouped by client. | `realm`, `username` |
| `list-user-credentials` | List a user's credential metadata (id, type, label, created date). No secret values. | `realm`, `username` |
| `list-user-sessions` | List a user's active sessions (start/last-access times, IP, clients used). | `realm`, `username` |
| `search-users-by-attribute` | Find users by a custom attribute key/value (exact match). Paginated. | `realm`, `attribute`, `value`, `first?`, `max?` |
| `create-user` | Create a user; returns the new id. Optional permanent initial password. Fails if username exists. | `realm`, `username`, `email?`, `firstName?`, `lastName?`, `enabled?` (def. true), `emailVerified?` (def. false), `password?` |
| `update-user` | Update profile fields of an existing user. Only supplied fields change; needs ≥1 field. | `realm`, `username`, `email?`, `firstName?`, `lastName?`, `emailVerified?` |
| `set-user-enabled` | Enable or disable an account. Disabling blocks login immediately. | `realm`, `username`, `enabled` |
| `delete-user` | Permanently delete a user. **Irreversible** — prefer `set-user-enabled(false)` for temporary blocks. | `realm`, `username` |
| `reset-user-password` | Set a new password. `temporary=true` forces a change at next login. | `realm`, `username`, `password`, `temporary?` (def. true) |
| `send-user-actions-email` | Email the user required actions (e.g. `VERIFY_EMAIL`, `UPDATE_PASSWORD`). Needs SMTP on the realm. | `realm`, `username`, `actions[]`, `lifespan?` (seconds) |
| `logout-user` | Revoke **all** of a user's active sessions, forcing re-authentication everywhere. | `realm`, `username` |
| `impersonate-user` | Start an impersonation session via the admin account. **Sensitive** — returns session/redirect data. | `realm`, `username` |
| `unlock-user` | Clear a user's brute-force lockout so they can sign in again. Does not change their password. | `realm`, `username` |
### Roles (`roles`, 15 tools)
Composite roles bundle other roles: whoever holds the parent also gets every child. For the
composite tools the parent is a realm role, or a client role when `clientId` is given, and each
entry in `children` is `{ roleName, clientId? }` (omit `clientId` for a realm role). All roles are
checked before anything is written, so a typo changes nothing.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-realm-roles` | List realm-level roles (id, name, description, composite flag). Search + paginate. | `realm`, `search?`, `first?`, `max?` |
| `list-client-roles` | List roles defined by a specific client (by clientId). | `realm`, `clientId` |
| `list-users-with-realm-role` | List users that have a given realm role assigned. | `realm`, `roleName`, `first?`, `max?` |
| `create-realm-role` | Create a realm-level role. Fails if the name already exists. | `realm`, `name`, `description?` |
| `update-realm-role` | Rename a realm role and/or change its description. Only supplied fields change; needs ≥1. | `realm`, `name`, `newName?`, `description?` |
| `delete-realm-role` | Delete a realm role by name. **Irreversible** — unmaps it from every user and group. | `realm`, `name` |
| `create-client-role` | Create a role owned by a client (by clientId). Fails if the name already exists on that client. | `realm`, `clientId`, `name`, `description?` |
| `delete-client-role` | Delete a client role by name. **Irreversible** — unmaps it from every user, group and composite. | `realm`, `clientId`, `name` |
| `assign-realm-role` | Assign a realm role to a user. Idempotent. | `realm`, `username`, `roleName` |
| `remove-realm-role` | Remove a realm role from a user. Idempotent. | `realm`, `username`, `roleName` |
| `assign-client-role` | Assign a client-level role to a user. Idempotent. | `realm`, `username`, `clientId`, `roleName` |
| `remove-client-role` | Remove a client-level role from a user. Idempotent. | `realm`, `username`, `clientId`, `roleName` |
| `list-composite-roles` | List the child roles inside a composite role (name, description, owning `clientId` or null). | `realm`, `roleName`, `clientId?` |
| `add-composite-roles` | Add child roles to a role, making it composite. Idempotent for children already present. | `realm`, `roleName`, `clientId?`, `children[]` |
| `remove-composite-roles` | Remove child roles from a composite role. The children themselves are kept. | `realm`, `roleName`, `clientId?`, `children[]` |
### Groups (`groups`, 7 tools)
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-groups` | List groups as a tree (id, name, path, nested subGroups). Search + paginate top-level groups. | `realm`, `search?`, `first?`, `max?` |
| `list-group-members` | List members of a group (by path or name): id, username, email, enabled. | `realm`, `group`, `first?`, `max?` |
| `create-group` | Create a top-level group, or a nested child when a `parent` (path/name) is supplied. | `realm`, `name`, `parent?` |
| `update-group` | Rename a group (by path or name). Members, subgroups and attributes are kept; the path changes. | `realm`, `group`, `newName` |
| `delete-group` | Delete a group (by path or name), including its subgroups. **Irreversible.** | `realm`, `group` |
| `add-user-to-group` | Add a user to a group (by path or name). Idempotent. | `realm`, `username`, `group` |
| `remove-user-from-group` | Remove a user from a group (by path or name). Idempotent. | `realm`, `username`, `group` |
### Clients (`clients`, 8 tools)
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-clients` | List clients (id, clientId, name, enabled, protocol, public flag). Filter by clientId; paginated. | `realm`, `clientId?`, `first?`, `max?` |
| `get-client` | Get one client by clientId (protocol, flow settings, redirect URIs, web origins). No secret. | `realm`, `clientId` |
| `get-client-secret` | Retrieve a confidential client's current secret. **Sensitive** — non-public clients only. | `realm`, `clientId` |
| `create-client` | Register a new client. Defaults to confidential standard-flow; toggle public / service-account. | `realm`, `clientId`, `name?`, `description?`, `publicClient?` (def. false), `standardFlowEnabled?` (def. true), `serviceAccountsEnabled?` (def. false), `redirectUris?`, `webOrigins?` |
| `update-client` | Update an existing client. Only supplied fields change; `redirectUris` / `webOrigins` **replace** the existing lists. Needs ≥1 field. | `realm`, `clientId`, `name?`, `description?`, `enabled?`, `publicClient?`, `standardFlowEnabled?`, `serviceAccountsEnabled?`, `authorizationServicesEnabled?`, `redirectUris?`, `webOrigins?` |
| `delete-client` | Delete a client, including its roles, secret and service account. **Irreversible.** | `realm`, `clientId` |
| `regenerate-client-secret` | Rotate a confidential client's secret and return the new value. **Sensitive**; old secret dies. | `realm`, `clientId` |
| `get-client-service-account` | Get the service-account user behind a client (id, username, enabled). Needs `serviceAccountsEnabled`. | `realm`, `clientId` |
### Client scopes and protocol mappers (`client-scopes`, 13 tools)
A client scope is a reusable bundle of protocol mappers that can be assigned to many clients.
Protocol mappers add claims to tokens, either directly on a client (`add-protocol-mapper`...) or on
a scope (`add-client-scope-protocol-mapper`...). Realm-wide *default* scopes (auto-assigned to new
clients) are not covered yet.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-client-scopes` | List the realm's client scopes, or (with `clientId`) the default and optional scopes assigned to a client. | `realm`, `clientId?` |
| `get-client-scope` | Get one scope by name: protocol, description, attributes and its protocol mappers. | `realm`, `name` |
| `create-client-scope` | Create a scope. Fails if the name already exists. | `realm`, `name`, `description?`, `protocol?` (def. `openid-connect`), `attributes?` |
| `update-client-scope` | Update description and/or attributes (keys are **merged**). Rename/protocol change = delete + create. Needs ≥1 field. | `realm`, `name`, `description?`, `attributes?` |
| `delete-client-scope` | Delete a scope and its mappers; detaches it from every client. **Irreversible.** | `realm`, `name` |
| `assign-client-scope-to-client` | Assign a scope to a client as `default` (always applied) or `optional` (only when requested). Idempotent. | `realm`, `clientId`, `scope`, `type?` (def. `default`) |
| `remove-client-scope-from-client` | Detach a scope from a client; `type` must match how it was assigned. Idempotent. | `realm`, `clientId`, `scope`, `type` |
| `add-client-scope-protocol-mapper` | Add a protocol mapper to a scope. Fails if the name already exists on it. | `realm`, `scope`, `name`, `protocolMapper`, `protocol?`, `config?` |
| `delete-client-scope-protocol-mapper` | Remove a mapper (by name) from a scope. **Irreversible.** | `realm`, `scope`, `name` |
| `list-protocol-mappers` | List the protocol mappers defined directly on a client (name, mapper type, config). | `realm`, `clientId` |
| `add-protocol-mapper` | Add a mapper to a client, e.g. type `oidc-usermodel-attribute-mapper`. Fails if the name already exists. | `realm`, `clientId`, `name`, `protocolMapper`, `protocol?` (def. `openid-connect`), `config?` |
| `update-protocol-mapper` | Change a mapper's config (looked up by name). Keys are **merged**; name and type can't change. | `realm`, `clientId`, `name`, `config` |
| `delete-protocol-mapper` | Remove a mapper (by name) from a client. **Irreversible.** | `realm`, `clientId`, `name` |
### Realms (`realms`, 9 tools)
Turn on event storage with `update-realm-events-config` before `list-events` /
`list-admin-events` (group `events`) return anything.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-realms` | List realms visible to the admin service account (id, realm, enabled). Needs realm-view. | _(none)_ |
| `get-realm` | Get a realm's key settings: enabled, login flags, token/session lifespans, SMTP-configured. | `realm` |
| `set-realm-enabled` | Enable or disable a realm. Disabling blocks **all** logins to it immediately. | `realm`, `enabled` |
| `create-realm` | Create a new, empty realm with Keycloak defaults. Fails if the name exists. | `realm`, `displayName?`, `enabled?` (def. true) |
| `update-realm-settings` | Update login options, security (`sslRequired`, brute force, `passwordPolicy`), token/session lifespans (seconds), locale and theme. Only supplied fields change; needs ≥1. | `realm`, `displayName?`, `registrationAllowed?`, `registrationEmailAsUsername?`, `loginWithEmailAllowed?`, `duplicateEmailsAllowed?`, `resetPasswordAllowed?`, `rememberMe?`, `verifyEmail?`, `editUsernameAllowed?`, `sslRequired?`, `bruteForceProtected?`, `failureFactor?`, `passwordPolicy?`, `accessTokenLifespan?`, `ssoSessionIdleTimeout?`, `ssoSessionMaxLifespan?`, `internationalizationEnabled?`, `defaultLocale?`, `supportedLocales?`, `organizationsEnabled?`, `loginTheme?` |
| `get-realm-smtp` | Read a realm's SMTP settings. The password is never returned, only `passwordSet`. | `realm` |
| `update-realm-smtp` | Configure outgoing email. Only supplied fields change; existing SMTP config is kept. Password is write-only. | `realm`, `host?`, `port?`, `from?`, `fromDisplayName?`, `replyTo?`, `auth?`, `user?`, `password?`, `ssl?`, `starttls?` |
| `update-realm-events-config` | Turn user-event and admin-event storage on/off (required before `list-events` / `list-admin-events` return data). | `realm`, `eventsEnabled?`, `eventsExpiration?` (seconds), `adminEventsEnabled?`, `adminEventsDetailsEnabled?` |
| `delete-realm` | Delete a realm and everything in it. **Irreversible.** `confirm` must repeat the realm name; the master realm and the server's auth realm are refused. | `realm`, `confirm` |
### Identity providers (`identity-providers`, 10 tools)
Identity-provider mappers turn claims from the external provider into user attributes, roles or
group memberships: call `list-identity-provider-mapper-types` first to get a valid mapper type and
its config keys. `config` on create/update may contain secrets and is never echoed back.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-identity-providers` | List configured identity providers (alias, provider type, display name, enabled). No secrets. | `realm` |
| `get-identity-provider` | Get one provider by alias, with its settings and config. Keycloak masks secret values. | `realm`, `alias` |
| `create-identity-provider` | Add a social/broker provider (`google`, `github`, `oidc`, `saml`, ...). `config` may contain secrets and is not echoed back. | `realm`, `alias`, `providerId`, `displayName?`, `enabled?` (def. true), `trustEmail?` (def. false), `config?` |
| `update-identity-provider` | Update a provider. Only supplied fields change; `config` keys are **merged** into the existing config. Needs ≥1 field. | `realm`, `alias`, `displayName?`, `enabled?`, `trustEmail?`, `config?` |
| `delete-identity-provider` | Delete a provider with its mappers and user links. **Irreversible** — prefer `enabled=false` to switch it off. | `realm`, `alias` |
| `list-identity-provider-mappers` | List a provider's mappers (id, name, mapper type, config). | `realm`, `alias` |
| `list-identity-provider-mapper-types` | List the mapper types a provider supports, with their config properties. | `realm`, `alias` |
| `create-identity-provider-mapper` | Add a mapper, e.g. `oidc-user-attribute-idp-mapper`. Include `syncMode` in `config`. Fails if the name exists. | `realm`, `alias`, `name`, `identityProviderMapper`, `config?` |
| `update-identity-provider-mapper` | Change a mapper's config (looked up by name). Keys are **merged**; name and type can't change. | `realm`, `alias`, `name`, `config` |
| `delete-identity-provider-mapper` | Remove a mapper (by name). Already-imported users keep what it set. **Irreversible.** | `realm`, `alias`, `name` |
### Authentication flows and required actions (`authentication`, 13 tools)
Flows decide how users log in (password, OTP, social login...). Flows are addressed by **alias**,
and steps ("executions") by id, or by provider id / display name when that is unambiguous.
Built-in flows can't be edited: `copy-authentication-flow` first, edit the copy, then bind it with
`set-realm-flow-binding`. Authenticator *configs* (e.g. OTP policy options on a step) and an identity
provider's first-broker-login flow (set on the identity provider) are not covered yet.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-authentication-flows` | List top-level flows (alias, description, built-in) and which realm bindings use each (`boundTo`). | `realm` |
| `get-authentication-flow` | Show a flow's steps in order with nesting level, requirement, provider and allowed requirement values. | `realm`, `flow` |
| `list-authenticator-providers` | List step types you can add (`auth-otp-form`, ...). `kind`: `authenticator`, `form-action` or `client`. | `realm`, `kind?` (def. `authenticator`) |
| `create-authentication-flow` | Create an empty top-level flow. Does nothing until it has steps and is bound. | `realm`, `alias`, `description?`, `providerId?` (def. `basic-flow`) |
| `copy-authentication-flow` | Copy a flow (usually a built-in) under a new alias, with its subflows and steps. | `realm`, `flow`, `newName` |
| `delete-authentication-flow` | Delete a custom flow. Built-in and realm-bound flows are refused. **Irreversible.** | `realm`, `flow` |
| `add-flow-execution` | Add a step to a flow/subflow. New steps start `DISABLED` unless `requirement` is given. | `realm`, `flow`, `provider`, `requirement?` |
| `add-authentication-subflow` | Add a nested subflow (`basic-flow` or `form-flow`) to group steps. Add steps into it using its alias as `flow`. | `realm`, `flow`, `alias`, `type?`, `description?`, `requirement?` |
| `update-flow-execution` | Set a step's requirement: `REQUIRED`, `ALTERNATIVE`, `CONDITIONAL` or `DISABLED`. | `realm`, `flow`, `execution`, `requirement` |
| `delete-flow-execution` | Remove a step. Deleting a subflow step deletes everything inside it. **Irreversible.** | `realm`, `flow`, `execution` |
| `set-realm-flow-binding` | Choose the flow used for `browser`, `registration`, `directGrant`, `resetCredentials`, `clientAuthentication` or `dockerAuthentication`. Immediate for all users — a flow that can't complete a login **locks everyone out**. | `realm`, `binding`, `flow` |
| `list-required-actions` | List required actions (`VERIFY_EMAIL`, `CONFIGURE_TOTP`, ...): enabled, default flag and priority. | `realm` |
| `update-required-action` | Enable/disable an action, rename it, or make it a *default* action assigned to every **new** user. Needs ≥1 field. | `realm`, `alias`, `enabled?`, `defaultAction?`, `name?` |
### Authorization services (`authorization`, 17 tools)
Authorization services add fine-grained access control to a client (the *resource server*). All
tools take the resource server's `clientId`, and everything is referenced by **name**. The model:
*resources* (what is protected) carry *scopes* (actions such as view/edit); *policies* say who or when
(role, user, group, time...); a *permission* ties resources/scopes to the policies that must be
satisfied. Build them in that order, then check the outcome with `evaluate-authorization`. Enable the
feature first with `update-client` (`authorizationServicesEnabled=true`, confidential clients only).
Editing an existing policy or permission, and importing a full settings JSON, are not covered: delete
and re-create. `export-authorization-settings` shows the full picture, including policy members.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `get-authorization-settings` | Get a resource server's settings: enforcement mode, decision strategy, remote resource management. | `realm`, `clientId` |
| `update-authorization-settings` | Change enforcement mode (`ENFORCING`/`PERMISSIVE`/`DISABLED`), decision strategy or remote management. `DISABLED` turns authorization off for the whole resource server. Needs ≥1 field. | `realm`, `clientId`, `policyEnforcementMode?`, `decisionStrategy?`, `allowRemoteResourceManagement?` |
| `export-authorization-settings` | Export the full authorization config (settings, scopes, resources, policies, permissions) as JSON, members by name. Can be large. | `realm`, `clientId` |
| `evaluate-authorization` | Dry-run: would a user be permitted to access a resource/scopes, and which policies decided it? Changes nothing. | `realm`, `clientId`, `username`, `resource?`, `scopes?[]`, `attributes?` |
| `list-authorization-scopes` | List the resource server's authorization scopes (actions such as `view`, `edit`). Not OAuth client scopes. | `realm`, `clientId`, `name?`, `first?`, `max?` |
| `create-authorization-scope` | Create an authorization scope. Fails if the name exists. | `realm`, `clientId`, `name`, `displayName?` |
| `delete-authorization-scope` | Delete a scope; it is removed from every resource and scope permission using it. **Irreversible.** | `realm`, `clientId`, `name` |
| `list-authorization-resources` | List protected resources with type, URIs and attached scopes. Filterable; paginated. | `realm`, `clientId`, `name?`, `type?`, `uri?`, `owner?`, `first?`, `max?` |
| `create-authorization-resource` | Create a protected resource. Scopes are given by name and must already exist. Fails if the name exists. | `realm`, `clientId`, `name`, `displayName?`, `type?`, `uris?[]`, `scopes?[]`, `ownerManagedAccess?` (def. false) |
| `update-authorization-resource` | Update a resource by name. `uris` and `scopes` **replace** the existing lists. Needs ≥1 field. | `realm`, `clientId`, `name`, `displayName?`, `type?`, `uris?[]`, `scopes?[]`, `ownerManagedAccess?` |
| `delete-authorization-resource` | Delete a protected resource. **Irreversible.** | `realm`, `clientId`, `name` |
| `list-authorization-policies` | List policies (name, type, logic, decision strategy). Use `export-authorization-settings` to see members. | `realm`, `clientId`, `name?`, `type?`, `first?`, `max?` |
| `create-authorization-policy` | Create a policy of type `role`, `user`, `group`, `client`, `aggregate`, `time` or `regex`. Members are given by name; `logic: NEGATIVE` inverts it. Grants nothing until a permission uses it. | `realm`, `clientId`, `name`, `type`, `description?`, `logic?`, `decisionStrategy?`, `roles?[]`, `users?[]`, `groups?[]`, `extendChildren?`, `clients?[]`, `policies?[]`, `settings?` |
| `delete-authorization-policy` | Delete a policy; permissions that used it lose it, which can silently widen or narrow access. **Irreversible.** | `realm`, `clientId`, `name` |
| `list-authorization-permissions` | List permissions (name, type, decision strategy); `details=true` adds the linked resources, scopes and policies. | `realm`, `clientId`, `name?`, `resource?`, `details?`, `first?`, `max?` |
| `create-authorization-permission` | Grant access: tie resources (or a `resourceType`) and/or scopes to the policies that must be met. `type`: `resource` or `scope`. Everything by name and must exist. | `realm`, `clientId`, `name`, `type`, `description?`, `resources?[]`, `resourceType?`, `scopes?[]`, `policies[]`, `decisionStrategy?` |
| `delete-authorization-permission` | Delete a permission; the resources and policies it linked are kept. **Irreversible.** | `realm`, `clientId`, `name` |
### Organizations (`organizations`, 15 tools)
Organizations group users into customers/tenants (Keycloak 26+), each with its own email domains and
optionally its own identity providers. Turn the feature on first with `update-realm-settings`
(`organizationsEnabled=true`). Organizations are addressed by **name or alias**, members by
**username**, invitations by the invited **email**. Organization groups and per-organization
identity-provider domain settings are not covered yet.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-organizations` | List organizations (name, alias, enabled, email domains). `search` matches name or domain. | `realm`, `search?`, `first?`, `max?` |
| `get-organization` | Get one organization by name or alias: description, redirect URL, domains, attributes and linked identity providers. | `realm`, `organization` |
| `create-organization` | Create an organization. `alias` defaults to the name. Fails if the name or alias exists. | `realm`, `name`, `alias?`, `description?`, `domains?[]`, `redirectUrl?`, `enabled?` (def. true), `attributes?` |
| `update-organization` | Update an organization. Only supplied fields change; `domains` **replace** the list, `attributes` are **merged**. Needs ≥1 field. | `realm`, `organization`, `newName?`, `alias?`, `description?`, `redirectUrl?`, `enabled?`, `domains?[]`, `attributes?` |
| `delete-organization` | Delete an organization with its memberships, invitations and IdP links. Users it manages may be deleted too. **Irreversible.** | `realm`, `organization` |
| `list-organization-members` | List members with their membership type (`MANAGED` = created through the organization, `UNMANAGED` = existing user who joined). | `realm`, `organization`, `search?`, `membershipType?`, `first?`, `max?` |
| `add-organization-member` | Add an existing user (by username) as an unmanaged member. Fails if already a member. | `realm`, `organization`, `username` |
| `remove-organization-member` | Remove a member. A managed member may be deleted with the membership. | `realm`, `organization`, `username` |
| `list-user-organizations` | List the organizations a user belongs to. | `realm`, `username` |
| `invite-organization-user` | Email an invitation. Existing users (matched by email) are invited as existing users; others can register. Needs SMTP. | `realm`, `organization`, `email`, `firstName?`, `lastName?` |
| `list-organization-invitations` | List invitations: email, name, status (`PENDING`/`EXPIRED`), sent and expiry times. Links are not returned. | `realm`, `organization`, `status?`, `email?`, `first?`, `max?` |
| `resend-organization-invitation` | Send an invitation again (identified by email). Needs SMTP. | `realm`, `organization`, `email` |
| `delete-organization-invitation` | Cancel an invitation (identified by email). **Irreversible.** | `realm`, `organization`, `email` |
| `link-organization-identity-provider` | Link an existing identity provider to an organization. A provider can belong to only one organization. | `realm`, `organization`, `alias` |
| `unlink-organization-identity-provider` | Detach an identity provider from an organization; the provider itself is kept. | `realm`, `organization`, `alias` |
### Realm import and export (`import-export`, 3 tools)
Back up a realm or copy its setup to another. `export-realm` writes realm configuration as JSON;
`partial-import-realm` loads resources into an existing realm and `import-realm` creates a new one.
A file is given as an **absolute path ending in `.json`**; set `KEYCLOAK_FILES_DIR` to confine every
read and write to one directory (see [Environment variables](#environment-variables)). Exports do
**not** contain users, and Keycloak masks secrets (`**********`) in them, so after an import the
secrets of clients, identity providers, SMTP and LDAP must be set again. Large exports should go to
a file rather than into the conversation.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `export-realm` | Export a realm as JSON: settings, flows, identity providers and optionally clients, groups and roles. Users are **not** included; secrets come back masked. `outputFile` saves it to disk (owner-readable only) and returns just a summary. | `realm`, `exportClients?` (def. true), `exportGroupsAndRoles?` (def. true), `outputFile?`, `overwrite?` (def. false) |
| `partial-import-realm` | Import users, clients, groups, roles and identity providers from a realm JSON into an **existing** realm. `ifResourceExists`: `FAIL` (default), `SKIP` or `OVERWRITE`. Masked secrets are dropped, not stored. | `realm`, `file?` or `data?`, `ifResourceExists?`, `include?[]` |
| `import-realm` | Create a **new** realm from a full realm JSON. `realmName` clones it under another name. Refuses existing realms and `master`; masked secrets are dropped. | `file?` or `data?`, `realmName?` |
### User federation (LDAP / Active Directory) (`federation`, 12 tools)
Federation providers let Keycloak authenticate users against an external directory. Providers and
their mappers are addressed by **name**. Secrets (the bind credential) are write-only: they are
never returned, and `get-user-federation-provider` only lists which ones are set.
Kerberos and custom federation providers can be listed, inspected, updated, synced and deleted, but
only LDAP/AD providers can be created. Editing an existing mapper and triggering a mapper sync
(group/role import) are not covered; delete and re-create a mapper to change it.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-user-federation-providers` | List providers: name, type, enabled, priority, edit mode and (LDAP) connection URL. | `realm` |
| `get-user-federation-provider` | Get one provider with its full config. Secrets omitted (`secretsSet` names them). | `realm`, `name` |
| `create-ldap-user-federation` | Connect an LDAP/AD server. `vendor` (`ad`, `rhds`, `tivoli`, `edirectory`, `other`) fills in the right attribute names; defaults to `READ_ONLY`, import on login, no periodic sync. | `realm`, `name`, `vendor`, `connectionUrl`, `usersDn`, `authType?` (def. `simple`), `bindDn?`, `bindCredential?`, `config?` |
| `update-user-federation-provider` | Change settings; `config` keys are **merged**, a stored bind credential is kept. `enabled=false` pauses it. | `realm`, `name`, `config` |
| `delete-user-federation-provider` | Delete a provider and its mappers. Keycloak also removes the users imported from it. **Irreversible.** | `realm`, `name` |
| `sync-user-federation-provider` | Import users now: `changed` (default) or `full`. Returns added/updated/removed/failed counts. | `realm`, `name`, `mode?` |
| `unlink-federated-users` | Turn all of a provider's users into ordinary local users (they then need a local password). Run before deleting a provider to keep its users. | `realm`, `name` |
| `remove-imported-federated-users` | Delete Keycloak's copies of all users imported from a provider. They are re-imported on next login/sync. **Irreversible** for Keycloak-only data. | `realm`, `name` |
| `list-ldap-mapper-types` | List the mapper types a provider supports, with their config properties. | `realm`, `provider` |
| `list-ldap-mappers` | List a provider's mappers (name, type, config). | `realm`, `provider` |
| `create-ldap-mapper` | Add a mapper (`user-attribute-ldap-mapper`, `group-ldap-mapper`, `role-ldap-mapper`, ...). | `realm`, `provider`, `name`, `mapperType`, `config?` |
| `delete-ldap-mapper` | Remove a mapper by name. **Irreversible.** | `realm`, `provider`, `name` |
### Events (`events`, 2 tools)
Both tools need event storage enabled (`update-realm-events-config`, group `realms`); otherwise
they return an empty list.
| Tool | Description | Arguments |
| ---- | ----------- | --------- |
| `list-events` | List login/user events (LOGIN, LOGIN_ERROR, LOGOUT, ...), newest first. Handy for failed-login debugging. | `realm`, `type?[]`, `username?`, `clientId?`, `ipAddress?`, `dateFrom?` (yyyy-MM-dd), `dateTo?` (yyyy-MM-dd), `first?`, `max?` |
| `list-admin-events` | List admin-API events (who created/updated/deleted what), newest first. | `realm`, `operationTypes?` (CREATE/UPDATE/DELETE/ACTION), `resourceTypes?`, `resourcePath?`, `first?`, `max?` |
---
## Usage tips
Once integrated, you can prompt Claude in natural language, for example:
- “List the first 10 users in the `financement-realm` realm whose name contains `dupont`.”
- “Show details for user `jdoe` in `financement-realm`, including their groups and realm roles.”
- “Disable the account `olduser` in `financement-realm`.”
- “Assign the `offline_access` realm role to `jdoe` in `financement-realm`.”
- “Set `jdoe`'s email to `jdoe@example.com` and mark it verified.”
- “Send `jdoe` a VERIFY_EMAIL and UPDATE_PASSWORD action email.”
- “Log `jdoe` out of all sessions in `financement-realm`.”
- “Create a `billing-admin` realm role and assign it to `jdoe`.”
- “Rotate the client secret for `my-backend` in `financement-realm`.”
- “Find all users in `financement-realm` with attribute `department = finance`.”
- “Why did `jdoe`'s login fail yesterday in `financement-realm`?” (login events)
- “Add a `department` claim mapper to the `my-backend` client.”
- “Make `billing-admin` a composite role that includes `offline_access`.”
- “Copy the `browser` flow to `browser-with-otp`, make OTP required, then bind it to the realm.”
- “Why can't `jdoe` view the `invoices` resource of `my-backend`?” (authorization evaluation)
- “Let the `finance` group view and edit `invoices` in `my-backend`.”
- “Export `financement-realm` to `/Users/me/backups/financement.json`.”
- “Clone `financement-realm` as `staging-realm` from that file.”
- “Create an organization `Acme` with the domain `acme.com`, then invite `anna@acme.com` to it.”
- “Connect `financement-realm` to our Active Directory at `ldaps://ad.example.com` and sync the users.”
Claude will pick the matching tool and fill in the arguments.
> ⚠️ **Destructive tools have no confirmation step.** Every `delete-*` tool,
> `remove-imported-federated-users`, `unlink-federated-users`, `logout-user`,
> `regenerate-client-secret`, `set-realm-enabled(false)`, `set-realm-flow-binding` and
> `partial-import-realm` with `OVERWRITE` take
> effect immediately, and most cannot be undone. `delete-realm` is the one exception: it needs
> a `confirm` argument repeating the realm name and refuses the `master` realm. A bad
> `set-realm-flow-binding` can lock everyone out of a realm; inspect the flow first with
> `get-authentication-flow`. To limit what the model can do, enable fewer groups with
> `KEYCLOAK_TOOLS` and grant the service account only the roles it needs.
---
## Troubleshooting
| Symptom | Likely cause / fix |
| ------- | ------------------ |
| Server won't connect in `claude mcp list` | Check absolute paths; run `npm install` so `node_modules/.bin/tsx` exists; run `npm run dev` manually to see stderr. |
| `401`/auth errors | Wrong `KEYCLOAK_CLIENT_ID`/`SECRET`, or the service account lacks admin roles. |
| Tool returns "not found" | Verify `realm`, `username`, `clientId`, or `group` are exact; identifiers are case-sensitive. |
| `get-client-secret` fails | Client is public (no secret) — only confidential clients have one. |
| `send-user-actions-email` fails | The **target realm** has no SMTP server configured. |
| `403` on realm/role/group writes | Service account lacks `manage-realm` (or `impersonation` for `impersonate-user`) on the target realm. |
| `403` on clients, scopes, mappers, identity providers or events | Needs `manage-clients`, `manage-identity-providers` or `view-events`; see [Keycloak setup](#keycloak-setup-service-account). |
| Missing users/clients in list | Service account lacks `view-users` / `view-clients` for that realm. |
| Server exits at startup with `Unknown KEYCLOAK_TOOLS group(s)` | A name in `KEYCLOAK_TOOLS` is misspelled. The message lists the valid groups; see [Tool groups](#tool-groups). |
| A tool is missing from the client | Its group is not enabled. Check the startup line on stderr (`N tools registered (groups: ...)`) and add the group to `KEYCLOAK_TOOLS`. |
| `list-events` / `list-admin-events` return `[]` | Event storage is off for that realm. Enable it with `update-realm-events-config`. |
| `Authorization services are not enabled on client ...` | Enable them with `update-client` (`authorizationServicesEnabled=true`); the client must be confidential (not public). |
| `create-authorization-*` says a scope/resource/policy `not found` | They are referenced by name and must exist first. Create in order: scopes, resources, policies, then the permission. |
| Import/export says `must be inside KEYCLOAK_FILES_DIR` or `Use an absolute path` | Paths must be absolute, end in `.json`, and (when `KEYCLOAK_FILES_DIR` is set) lie inside it. |
| Imported clients/identity providers can't authenticate | Exports mask secrets and the import drops them. Regenerate client secrets (`regenerate-client-secret`) and set provider secrets again. |
| `Organizations are not enabled in realm ...` | Turn the feature on with `update-realm-settings` (`organizationsEnabled=true`). |
| `invite-organization-user` fails | The realm has no SMTP server configured; see `update-realm-smtp`. |
| LDAP sync reports `failed` users or nothing is imported | Check `connectionUrl`, `usersDn` and the bind credentials with `get-user-federation-provider`; `list-ldap-mappers` shows how attributes are mapped. |
| Changes not visible in Claude Desktop | Fully restart the app after editing the config. |
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues