Keycloak Admin

mcp-keycloak-admin

Model Context Protocol（MCP）を使用して、Keycloak インスタンスを Admin REST API 経由で管理する MCP サーバーです。デフォルトで安全に動作し、設定可能で、クリーンかつテスト駆動のアーキテクチャで構築されています。

Keycloak 26.x に対応しています（26.0.5 で検証済み）。

インストール

インストールは不要です。npx から直接実行できます。

npx -y mcp-keycloak-admin

このサーバーは stdio 経由で MCP を使用するため、通常は手動で実行するのではなく、MCP クライアントに接続して使用します。MCP クライアントでの使用方法をご覧ください。初めてお使いになる場合は、クイックスタートでローカルの Keycloak とクライアント設定を数分で準備できます。

特長

MCP クライアント（アシスタント、IDE、カスタムエージェント）から Keycloak を管理するには、管理コンソールへの直接アクセスを許可せずに、ユーザーの検索、ロールの管理、イベントの読み取りなどの日常的な操作を MCP ツールとして公開する必要があります。このサーバーは、破壊的な操作が気付かないうちに実行されないよう、強力な安全策を備えています。

機能

• 2 つの認証モードを設定で選択できます。
  • service_account — サービスアカウントを持つ機密クライアント（推奨。管理者パスワードを保存する必要はありません）。
  • password — 管理者のユーザー名とパスワードを使用する admin-cli クライアント。
• デフォルトで安全：
  • READ_ONLY モードでは、すべての書き込み／破壊的ツールが非表示になります。
  • ALLOWED_REALMS により、サーバーが操作できるレルムを制限します。
  • 破壊的な操作には明示的な確認が必要です（ネイティブ MCP エリシテーションを使用し、エリシテーションに対応しないクライアント向けには confirm: true パラメーターにフォールバックします）。
• クリーンアーキテクチャ：フレームワークに依存しないドメイン、アプリケーションのユースケース、インフラストラクチャアダプターで構成されています。ビジネス上の概念を生の文字列や数値として扱うことはなく、すべて検証済みの値オブジェクトです。

要件

• Node.js >= 20
• 接続可能な Keycloak 26.x サーバー

MCP クライアントでの使用方法

MCP クライアントの設定にサーバーを追加します。

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

mcp-admin クライアントを作成し、必要最小限のロールを付与する方法については、docs/setup-keycloak.mdをご覧ください。

複数の Keycloak インスタンス

各サーバーエントリーは、1 つの Keycloak（ベース URL、レルム、認証情報の組み合わせ）を対象とします。複数の環境を管理する場合は、インスタンスごとに 1 つのエントリーを追加してください。それぞれが独自の認証情報と安全策を持ち、完全に分離されます。

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

クライアントはサーバーごとにツールの名前空間を分けます（例：kc-prod:keycloak_user_delete）。そのため、誤った環境に対して操作を実行するリスクはありません。これは推奨されるパターンです。たとえば、本番環境を READ_ONLY に保ちながら、プレプロダクション環境では書き込みを許可できます。

設定

変数	必須	説明
KEYCLOAK_BASE_URL	はい	Keycloak サーバーのベース URL（末尾にスラッシュを付けないでください）。
KEYCLOAK_REALM	はい	サーバーが動作するレルム。
AUTH_MODE	はい	service_account または password。
KC_CLIENT_ID	service_account の場合	機密クライアント ID（例：mcp-admin）。
KC_CLIENT_SECRET	service_account の場合	クライアントシークレット。
KC_ADMIN_USERNAME	password の場合	管理者のユーザー名。
KC_ADMIN_PASSWORD	password の場合	管理者のパスワード。
KC_ADMIN_REALM	いいえ（デフォルトは master）	管理者ユーザーが属するレルム（password モード）。
READ_ONLY	いいえ（デフォルトは false）	true の場合、書き込み／破壊的なツールは登録されません。
ALLOWED_REALMS	いいえ	カンマ区切りの許可リストに指定するレルム。空の場合はすべてが対象です。

完全な例は .env.example にあります。

ツール

レベル：[R] 読み取り専用 · [W] 書き込み · [D] 破壊的（確認が必要）。各ツールには対応する MCP アノテーション（readOnlyHint／destructiveHint／idempotentHint）が付与されています。

現在実装されているツール：

注： この表は main ブランチの内容を示しており、上記のバージョンバッジに記載された最新の npm リリースより先行している場合があります。インストール環境で利用できる内容を確認するには、npm view mcp-keycloak-admin version を実行し、mcp-keycloak-admin@latest を指定してください。 | ツール | レベル | 説明 | | ------------------------------------------- | ----- | ------------------------------------------------------------------- | | keycloak_user_search | R | メールアドレス、ユーザー名、またはフリーテキストでレルムユーザーを検索します。 | | keycloak_user_get | R | ID を指定して単一のユーザーを取得します。 | | keycloak_user_sessions_list | R | ユーザーのアクティブなセッションを一覧表示します。 | | keycloak_user_create | W | レルムユーザーを作成します。 | | keycloak_user_update | W | ユーザーのメールアドレス、名前、または有効フラグを更新します。 | | keycloak_user_set_enabled | W | ユーザーを有効または無効にします。 | | keycloak_user_send_action_email | W | 必須アクションのメールを送信します。 | | keycloak_user_reset_password | D | ユーザーの新しいパスワードを設定します。 | | keycloak_user_logout | D | ユーザーのすべてのセッションを取り消します。 | | keycloak_user_delete | D | ユーザーを完全に削除します（ID とユーザー名が一致する必要があります）。 | | keycloak_role_list | R | レルムロールを一覧表示します。 | | keycloak_user_roles_get | R | ユーザーのレルムロールを一覧表示します。 | | keycloak_user_role_assign | W | ユーザーにレルムロールを付与します。 | | keycloak_user_role_unassign | D | ユーザーからレルムロールを取り消します。 | | keycloak_client_roles_list | R | クライアントに定義されたロールを一覧表示します。 | | keycloak_user_client_roles_get | R | ユーザーのクライアントロールを一覧表示します。 | | keycloak_user_client_role_assign | W | ユーザーにクライアントロールを付与します。 | | keycloak_user_client_role_unassign | D | ユーザーからクライアントロールを取り消します。 | | keycloak_client_list | R | レルムのクライアントを一覧表示します。 | | keycloak_client_create | W | レルムクライアントを作成します。 | | keycloak_client_update | W | クライアントを更新します（有効、パブリック、リダイレクト URI、CORS Web オリジン）。 | | keycloak_client_delete | D | クライアントを削除します。 | | keycloak_client_get | R | clientId を指定してクライアントを取得します。 | | keycloak_client_get_secret | R | クライアントシークレットを読み取ります（reveal が指定されない限りマスクされます）。 | | keycloak_client_scopes_list | R | レルムのクライアントスコープを一覧表示します。 | | keycloak_client_default_scopes_get | R | クライアントのデフォルトスコープを一覧表示します。 | | keycloak_client_mappers_list | R | クライアントのプロトコルマッパーを一覧表示します。 | | keycloak_client_scope_assign | W | クライアントにデフォルトスコープを追加します。 | | keycloak_client_scope_unassign | D | クライアントからデフォルトスコープを削除します。 | | keycloak_client_regenerate_secret | D | クライアントシークレットを再生成します（古いシークレットは使用できなくなります）。 | | keycloak_group_list | R | レルムのトップレベルグループを一覧表示します。 | | keycloak_group_members_list | R | グループのメンバーを一覧表示します。 | | keycloak_user_groups_list | R | ユーザーが所属するグループを一覧表示します。 | | keycloak_group_create | W | トップレベルグループを作成します。 | | keycloak_group_member_add | W | ユーザーをグループに追加します。 | | keycloak_group_role_assign | W | グループにレルムロールを付与します。 | | keycloak_group_member_remove | D | グループからユーザーを削除します。 | | keycloak_group_delete | D | グループを削除します。 | | keycloak_idp_list | R | ID プロバイダーを一覧表示します。 | | keycloak_idp_get | R | エイリアスを指定して ID プロバイダーを取得します。 | | keycloak_idp_mappers_list | R | ID プロバイダーのマッパーを一覧表示します。 | | keycloak_idp_create | W | ID プロバイダーを作成します。 | | keycloak_idp_delete | D | ID プロバイダーを削除します。 | | keycloak_federation_list | R | ユーザーフェデレーション（LDAP/Kerberos）プロバイダーを一覧表示します。 | | keycloak_federation_get | R | ID を指定してフェデレーションプロバイダーを取得します。 | | keycloak_federation_sync | W | ユーザー同期（全件または変更分）を実行します。 | | keycloak_auth_flows_list | R | 認証フローを一覧表示します。 | | keycloak_auth_required_actions_list | R | 必須アクションを一覧表示します。 | | keycloak_auth_required_action_set_enabled | W | 必須アクションを有効または無効にします。 | | keycloak_authz_resources_list | R | クライアントの認可リソースを一覧表示します。 | | keycloak_authz_policies_list | R | クライアントの認可ポリシーを一覧表示します。 | | keycloak_authz_permissions_list | R | クライアントの認可パーミッションを一覧表示します。 | | keycloak_events_login | R | 最近のログインイベントを読み取ります（フィルター可能）。 | | keycloak_events_admin | R | 最近の管理イベントを読み取ります。 | | keycloak_realm_get_config | R | 主要なレルム設定フラグを読み取ります。 | | keycloak_server_info | R | Keycloak サーバーのバージョンを読み取ります。 | パラメーターと使用例については、docs/users.md、docs/roles.md、 docs/clients.md、docs/groups.md、docs/events-realm.mdを参照してください。安全モデルについては docs/security.mdを参照してください。

ロードマップ

アーキテクチャは、薄いユースケースとツールを追加しながら拡張できるように設計されています。残っている候補は、認可ポリシー／権限の CRUD と評価、 認証フローの変更（実行のコピー／追加）、高度なフェデレーションおよび ID プロバイダーの設定です。追加方法については、docs/development.mdを参照してください。

開発

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/

リリースは自動化されています。docs/releasing.mdを参照してください。

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.mdをお読みください。

ライセンス

MIT