Keycloak Admin

io.github.mrz1880由 GitHub 帳號 mrz1880 發布v0.2.3更新於 Oct 24, 2026

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

概覽

AI 產生的概覽

本機 MCP 伺服器,讓助理透過 Keycloak Admin REST API 管理 Keycloak 26.x 領域中的使用者、角色、用戶端、群組、身分提供者與事件。

可以做什麼
  • 搜尋、讀取、建立、更新、啟用或停用、刪除領域使用者,查看工作階段、寄送操作郵件、重設密碼與登出工作階段
  • 列出、指派與撤銷使用者及群組的領域角色與用戶端角色
  • 列出、建立、更新與刪除用戶端,讀取或重新產生用戶端密鑰,管理預設範圍與通訊協定對應器
  • 列出、建立與刪除群組,新增或移除成員,為群組授予角色
  • 列出、建立與刪除身分提供者及其對應器,列出使用者聯合提供者並觸發同步
  • 讀取驗證流程、必要動作、授權資源、原則與權限、登入與管理員事件、領域設定與伺服器版本
適用情境
適合讓助理或 IDE 代理執行日常 Keycloak 維運——查詢使用者、管理角色、用戶端與群組、讀取事件——而不必交出原始管理主控台。特別適合希望在這些操作外加上唯讀模式與領域允許清單等防護的團隊。
執行需求
需要 Node.js 20 以上版本,以及可連線的 Keycloak 26.x 伺服器。必要環境變數:KEYCLOAK_BASE_URL、KEYCLOAK_REALM 與 AUTH_MODE。service_account 模式需 KC_CLIENT_ID 與 KC_CLIENT_SECRET;password 模式需 KC_ADMIN_USERNAME 與 KC_ADMIN_PASSWORD,可選 KC_ADMIN_REALM。另有選用的 READ_ONLY 與 ALLOWED_REALMS。以 stdio 在本機執行,通常透過 npx 啟動。
安裝前請注意
伺服器持有管理員憑證 KC_CLIENT_SECRET 或 KC_ADMIN_PASSWORD,可對領域進行廣泛控制。寫入與破壞性工具會變更真實資料——刪除使用者、用戶端、群組與身分提供者,重設密碼,撤銷工作階段,重新產生用戶端密鑰(舊密鑰隨即失效)以及觸發聯合同步。破壞性工具會要求確認,但仍建議設定 READ_ONLY 與 ALLOWED_REALMS(尤其是正式環境),並只授予用戶端最小權限角色。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Keycloak Admin,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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:

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

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

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

VariableRequiredDescription
KEYCLOAK_BASE_URLyesBase URL of the Keycloak server (no trailing slash).
KEYCLOAK_REALMyesRealm the server operates on.
AUTH_MODEyesservice_account or password.
KC_CLIENT_IDif service_accountConfidential client id (e.g. mcp-admin).
KC_CLIENT_SECRETif service_accountClient secret.
KC_ADMIN_USERNAMEif passwordAdmin username.
KC_ADMIN_PASSWORDif passwordAdmin password.
KC_ADMIN_REALMno (default master)Realm holding the admin user (password mode).
READ_ONLYno (default false)When true, write/destructive tools are not registered.
ALLOWED_REALMSnoComma-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.

ToolLevelDescription
keycloak_user_searchRSearch realm users by email, username or free text.
keycloak_user_getRFetch a single user by id.
keycloak_user_sessions_listRList a user's active sessions.
keycloak_user_createWCreate a realm user.
keycloak_user_updateWUpdate a user's email, name or enabled flag.
keycloak_user_set_enabledWEnable or disable a user.
keycloak_user_send_action_emailWSend a required-actions email.
keycloak_user_reset_passwordDSet a new password for a user.
keycloak_user_logoutDRevoke all of a user's sessions.
keycloak_user_deleteDPermanently delete a user (id + username must match).
keycloak_role_listRList realm roles.
keycloak_user_roles_getRList a user's realm roles.
keycloak_user_role_assignWGrant a realm role to a user.
keycloak_user_role_unassignDRevoke a realm role from a user.
keycloak_client_roles_listRList the roles defined on a client.
keycloak_user_client_roles_getRList a user's client roles.
keycloak_user_client_role_assignWGrant a client role to a user.
keycloak_user_client_role_unassignDRevoke a client role from a user.
keycloak_client_listRList the realm clients.
keycloak_client_createWCreate a realm client.
keycloak_client_updateWUpdate a client (enabled, public, redirect URIs, CORS web origins).
keycloak_client_deleteDDelete a client.
keycloak_client_getRFetch a client by its clientId.
keycloak_client_get_secretRRead a client secret (masked unless reveal).
keycloak_client_scopes_listRList the realm's client scopes.
keycloak_client_default_scopes_getRList a client's default scopes.
keycloak_client_mappers_listRList a client's protocol mappers.
keycloak_client_scope_assignWAdd a default scope to a client.
keycloak_client_scope_unassignDRemove a default scope from a client.
keycloak_client_regenerate_secretDRegenerate a client secret (old one stops working).
keycloak_group_listRList the realm's top-level groups.
keycloak_group_members_listRList the members of a group.
keycloak_user_groups_listRList the groups a user belongs to.
keycloak_group_createWCreate a top-level group.
keycloak_group_member_addWAdd a user to a group.
keycloak_group_role_assignWGrant a realm role to a group.
keycloak_group_member_removeDRemove a user from a group.
keycloak_group_deleteDDelete a group.
keycloak_idp_listRList identity providers.
keycloak_idp_getRFetch an identity provider by alias.
keycloak_idp_mappers_listRList an identity provider's mappers.
keycloak_idp_createWCreate an identity provider.
keycloak_idp_deleteDDelete an identity provider.
keycloak_federation_listRList user federation (LDAP/Kerberos) providers.
keycloak_federation_getRFetch a federation provider by id.
keycloak_federation_syncWTrigger a user sync (full or changed).
keycloak_auth_flows_listRList authentication flows.
keycloak_auth_required_actions_listRList required actions.
keycloak_auth_required_action_set_enabledWEnable/disable a required action.
keycloak_authz_resources_listRList a client's authorization resources.
keycloak_authz_policies_listRList a client's authorization policies.
keycloak_authz_permissions_listRList a client's authorization permissions.
keycloak_events_loginRRead recent login events (filterable).
keycloak_events_adminRRead recent admin events.
keycloak_realm_get_configRRead key realm configuration flags.
keycloak_server_infoRRead 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/

Releases are automated — see docs/releasing.md.

Contributing

Contributions are welcome — please read CONTRIBUTING.md.

License

MIT

來源:README.md,提交 8f97751

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.2.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分