{
  "markdown": "# mcp-keycloak-admin\n\n[![npm version](https://img.shields.io/npm/v/mcp-keycloak-admin.svg)](https://www.npmjs.com/package/mcp-keycloak-admin)\n[![CI](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/ci.yml/badge.svg)](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/codeql.yml/badge.svg)](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/codeql.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server to\nadminister a [Keycloak](https://www.keycloak.org) instance through its Admin\nREST API. Safe by default, configurable, and built with a clean, test-driven\narchitecture.\n\nCompatible with **Keycloak 26.x** (validated against 26.0.5).\n\n## Install\n\nNo install needed — run it straight from npm with `npx`:\n\n```bash\nnpx -y mcp-keycloak-admin\n```\n\nThe server speaks MCP over stdio, so you normally wire it into an MCP client\nrather than running it by hand — see [Usage with an MCP client](#usage-with-an-mcp-client).\nNew to it? The [Quickstart](docs/quickstart.md) spins up a local Keycloak and a\nclient config in a couple of minutes.\n\n## Why\n\nAdministering Keycloak from an MCP client (an assistant, an IDE, a custom agent)\nmeans exposing day-to-day operations — searching users, managing roles, reading\nevents — as MCP tools, without handing over a raw admin console. This server\ndoes that with strong guardrails so destructive actions never happen silently.\n\n## Features\n\n- **Two authentication modes**, selectable by configuration:\n  - `service_account` — a confidential client with a service account\n    (recommended; no admin password stored).\n  - `password` — the `admin-cli` client with an admin username/password.\n- **Safe by default:**\n  - `READ_ONLY` mode hides every write/destructive tool.\n  - `ALLOWED_REALMS` restricts which realms the server may operate on.\n  - Destructive operations require explicit confirmation (native MCP\n    elicitation, with a `confirm: true` parameter fallback for clients that do\n    not support elicitation).\n- **Clean Architecture**: a framework-free domain, application use cases, and\n  infrastructure adapters. No business concept travels as a raw string or\n  number — every one is a validated value object.\n\n## Requirements\n\n- Node.js >= 20\n- A reachable Keycloak 26.x server\n\n## Usage with an MCP client\n\nAdd the server to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"keycloak-admin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-keycloak-admin\"],\n      \"env\": {\n        \"KEYCLOAK_BASE_URL\": \"http://localhost:8080\",\n        \"KEYCLOAK_REALM\": \"demo-realm\",\n        \"AUTH_MODE\": \"service_account\",\n        \"KC_CLIENT_ID\": \"mcp-admin\",\n        \"KC_CLIENT_SECRET\": \"your-secret\"\n      }\n    }\n  }\n}\n```\n\nSee [docs/setup-keycloak.md](docs/setup-keycloak.md) to create the `mcp-admin`\nclient and grant it the least-privilege roles it needs.\n\n### Multiple Keycloak instances\n\nEach server entry targets **one** Keycloak (one base URL + realm + auth). To\nmanage several environments, add **one entry per instance** — each fully\nisolated, with its own credentials and guardrails:\n\n```json\n{\n  \"mcpServers\": {\n    \"kc-preprod\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-keycloak-admin\"],\n      \"env\": {\n        \"KEYCLOAK_BASE_URL\": \"https://preprod.example.com\",\n        \"KEYCLOAK_REALM\": \"preprod-realm\",\n        \"AUTH_MODE\": \"service_account\",\n        \"KC_CLIENT_ID\": \"mcp-admin\",\n        \"KC_CLIENT_SECRET\": \"…\",\n        \"ALLOWED_REALMS\": \"preprod-realm\"\n      }\n    },\n    \"kc-prod\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-keycloak-admin\"],\n      \"env\": {\n        \"KEYCLOAK_BASE_URL\": \"https://auth.example.com\",\n        \"KEYCLOAK_REALM\": \"prod-realm\",\n        \"AUTH_MODE\": \"service_account\",\n        \"KC_CLIENT_ID\": \"mcp-admin\",\n        \"KC_CLIENT_SECRET\": \"…\",\n        \"READ_ONLY\": \"true\",\n        \"ALLOWED_REALMS\": \"prod-realm\"\n      }\n    }\n  }\n}\n```\n\nThe client namespaces the tools per server (e.g. `kc-prod:keycloak_user_delete`),\nso there's no risk of running an operation against the wrong environment. This\nis the recommended pattern: you can, for example, keep production `READ_ONLY`\nwhile preprod stays writable.\n\n## Configuration\n\n| Variable            | Required              | Description                                              |\n| ------------------- | --------------------- | -------------------------------------------------------- |\n| `KEYCLOAK_BASE_URL` | yes                   | Base URL of the Keycloak server (no trailing slash).     |\n| `KEYCLOAK_REALM`    | yes                   | Realm the server operates on.                            |\n| `AUTH_MODE`         | yes                   | `service_account` or `password`.                         |\n| `KC_CLIENT_ID`      | if `service_account`  | Confidential client id (e.g. `mcp-admin`).               |\n| `KC_CLIENT_SECRET`  | if `service_account`  | Client secret.                                           |\n| `KC_ADMIN_USERNAME` | if `password`         | Admin username.                                          |\n| `KC_ADMIN_PASSWORD` | if `password`         | Admin password.                                          |\n| `KC_ADMIN_REALM`    | no (default `master`) | Realm holding the admin user (`password` mode).          |\n| `READ_ONLY`         | no (default `false`)  | When `true`, write/destructive tools are not registered. |\n| `ALLOWED_REALMS`    | no                    | Comma-separated allow-list of realms. Empty = all.       |\n\nA full example lives in [`.env.example`](.env.example).\n\n## Tools\n\nLevels: **[R]** read-only · **[W]** write · **[D]** destructive (requires\nconfirmation). Every tool carries the matching MCP annotations\n(`readOnlyHint` / `destructiveHint` / `idempotentHint`).\n\nCurrently implemented:\n\n> **Note:** this table tracks the `main` branch, which can run ahead of the\n> latest npm release shown by the version badge above. To confirm what's\n> available in your install, check `npm view mcp-keycloak-admin version` and pin\n> `mcp-keycloak-admin@latest`.\n\n| Tool                                        | Level | Description                                                         |\n| ------------------------------------------- | ----- | ------------------------------------------------------------------- |\n| `keycloak_user_search`                      | R     | Search realm users by email, username or free text.                 |\n| `keycloak_user_get`                         | R     | Fetch a single user by id.                                          |\n| `keycloak_user_sessions_list`               | R     | List a user's active sessions.                                      |\n| `keycloak_user_create`                      | W     | Create a realm user.                                                |\n| `keycloak_user_update`                      | W     | Update a user's email, name or enabled flag.                        |\n| `keycloak_user_set_enabled`                 | W     | Enable or disable a user.                                           |\n| `keycloak_user_send_action_email`           | W     | Send a required-actions email.                                      |\n| `keycloak_user_reset_password`              | D     | Set a new password for a user.                                      |\n| `keycloak_user_logout`                      | D     | Revoke all of a user's sessions.                                    |\n| `keycloak_user_delete`                      | D     | Permanently delete a user (id + username must match).               |\n| `keycloak_role_list`                        | R     | List realm roles.                                                   |\n| `keycloak_user_roles_get`                   | R     | List a user's realm roles.                                          |\n| `keycloak_user_role_assign`                 | W     | Grant a realm role to a user.                                       |\n| `keycloak_user_role_unassign`               | D     | Revoke a realm role from a user.                                    |\n| `keycloak_client_roles_list`                | R     | List the roles defined on a client.                                 |\n| `keycloak_user_client_roles_get`            | R     | List a user's client roles.                                         |\n| `keycloak_user_client_role_assign`          | W     | Grant a client role to a user.                                      |\n| `keycloak_user_client_role_unassign`        | D     | Revoke a client role from a user.                                   |\n| `keycloak_client_list`                      | R     | List the realm clients.                                             |\n| `keycloak_client_create`                    | W     | Create a realm client.                                              |\n| `keycloak_client_update`                    | W     | Update a client (enabled, public, redirect URIs, CORS web origins). |\n| `keycloak_client_delete`                    | D     | Delete a client.                                                    |\n| `keycloak_client_get`                       | R     | Fetch a client by its clientId.                                     |\n| `keycloak_client_get_secret`                | R     | Read a client secret (masked unless `reveal`).                      |\n| `keycloak_client_scopes_list`               | R     | List the realm's client scopes.                                     |\n| `keycloak_client_default_scopes_get`        | R     | List a client's default scopes.                                     |\n| `keycloak_client_mappers_list`              | R     | List a client's protocol mappers.                                   |\n| `keycloak_client_scope_assign`              | W     | Add a default scope to a client.                                    |\n| `keycloak_client_scope_unassign`            | D     | Remove a default scope from a client.                               |\n| `keycloak_client_regenerate_secret`         | D     | Regenerate a client secret (old one stops working).                 |\n| `keycloak_group_list`                       | R     | List the realm's top-level groups.                                  |\n| `keycloak_group_members_list`               | R     | List the members of a group.                                        |\n| `keycloak_user_groups_list`                 | R     | List the groups a user belongs to.                                  |\n| `keycloak_group_create`                     | W     | Create a top-level group.                                           |\n| `keycloak_group_member_add`                 | W     | Add a user to a group.                                              |\n| `keycloak_group_role_assign`                | W     | Grant a realm role to a group.                                      |\n| `keycloak_group_member_remove`              | D     | Remove a user from a group.                                         |\n| `keycloak_group_delete`                     | D     | Delete a group.                                                     |\n| `keycloak_idp_list`                         | R     | List identity providers.                                            |\n| `keycloak_idp_get`                          | R     | Fetch an identity provider by alias.                                |\n| `keycloak_idp_mappers_list`                 | R     | List an identity provider's mappers.                                |\n| `keycloak_idp_create`                       | W     | Create an identity provider.                                        |\n| `keycloak_idp_delete`                       | D     | Delete an identity provider.                                        |\n| `keycloak_federation_list`                  | R     | List user federation (LDAP/Kerberos) providers.                     |\n| `keycloak_federation_get`                   | R     | Fetch a federation provider by id.                                  |\n| `keycloak_federation_sync`                  | W     | Trigger a user sync (full or changed).                              |\n| `keycloak_auth_flows_list`                  | R     | List authentication flows.                                          |\n| `keycloak_auth_required_actions_list`       | R     | List required actions.                                              |\n| `keycloak_auth_required_action_set_enabled` | W     | Enable/disable a required action.                                   |\n| `keycloak_authz_resources_list`             | R     | List a client's authorization resources.                            |\n| `keycloak_authz_policies_list`              | R     | List a client's authorization policies.                             |\n| `keycloak_authz_permissions_list`           | R     | List a client's authorization permissions.                          |\n| `keycloak_events_login`                     | R     | Read recent login events (filterable).                              |\n| `keycloak_events_admin`                     | R     | Read recent admin events.                                           |\n| `keycloak_realm_get_config`                 | R     | Read key realm configuration flags.                                 |\n| `keycloak_server_info`                      | R     | Read the Keycloak server version.                                   |\n\nSee [docs/users.md](docs/users.md), [docs/roles.md](docs/roles.md),\n[docs/clients.md](docs/clients.md), [docs/groups.md](docs/groups.md) and\n[docs/events-realm.md](docs/events-realm.md) for parameters and examples, and\n[docs/security.md](docs/security.md) for the safety model.\n\n## Roadmap\n\nThe architecture is designed to keep growing as thin use cases + tools.\nRemaining candidates: authorization policy/permission CRUD and evaluation,\nauthentication flow mutation (copy/add executions), and advanced federation and\nidentity-provider configuration. See [docs/development.md](docs/development.md)\nfor how to add one.\n\n## Development\n\n```bash\nnpm install\nnpm test              # unit tests\nnpm run test:integration  # spins up a real Keycloak 26 via Testcontainers (needs Docker)\nnpm run check         # typecheck + lint + format check + unit tests\nnpm run build         # bundle to dist/\n```\n\nReleases are automated — see [docs/releasing.md](docs/releasing.md).\n\n## Contributing\n\nContributions are welcome — please read [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 14589,
  "sha": "2ee94a43b6c6405056e5bd7166dddc5d38fe975eae258bd625728ea9112545a6",
  "repo_slug": "mrz1880/mcp-keycloak-admin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mrz1880_mcp_keycloak_admin_a78f855d/readme"
}