Keycloak MCP Server

Keycloak MCP サーバー

Keycloak の管理を行う Model Context Protocol（MCP）サーバーです。Claude などの AI アシスタントが、Keycloak Admin REST API を通じてユーザー、グループ、ロール、セッションを管理し、クライアント、イベント、レルムのセキュリティ状態を確認できます。最小権限での認証を採用し、すべての書き込み操作にガードレールを設けています。

警告

このサーバーは、指定した Keycloak アカウントの権限で動作します。必要なロールだけを持つ専用のサービスアカウントクライアントを使用し、ブートストラップ管理者は決して使用しないでください。データを変更するツールはすべて、デフォルトで確認を求めます。また、読み取り専用モードも利用できます。セキュリティを参照してください。

主な特長

• 7 つのツールセットに 24 個のツールがあり、ツールセットごとに有効化できます。デフォルトのセット（core、groups、roles）は小規模で、それ以外はすべてオプトインです。
• 最小権限での認証。 推奨されるグラントはサービスアカウントを使う client_credentials です。パスワードグラントも引き続き利用できます。認証情報にデフォルト値はないため、設定が不足している場合はすぐにエラーになります。
• ガードレール。 読み取り専用モード、レルムの許可リスト、master レルムへの書き込み保護、すべての変更に対するプレビュー後の confirm: true フローを備えています。管理者権限の付与は、複合ロールや親グループを通じたものも検出します。
• 4 つのガイド付きプロンプト（オンボーディング、オフボーディング、セキュリティ監査、ログイン失敗の調査）と、レルム名補完機能を備えたレルムおよびユーザー向けの MCP リソース。
• 出力スキーマを備えた 構造化されたページ分割出力。シークレットや認証情報が返されたり、ログに記録されたりすることはありません。
• Claude Desktop、Claude Code、VS Code、Cursor、およびすべての stdio MCP クライアントで動作します。Node.js 22 以降が必要です。

動作の仕組み

MCP クライアントはサーバーをローカルの子プロセスとして起動し、stdio 経由で通信します。すべてのツール呼び出しはガードを通過した後、Keycloak へのログインを管理してアクセストークンをキャッシュする単一のゲートウェイを経由します。

確認付きの呼び出しの例

データを変更するツールはすべて、データを削除または取り消す 破壊的 な操作か、ID、認証情報、権限、保護機構を変更する 機微な 操作です。たとえば、user_update や user_role_assign が該当します。confirm: true を指定せずに呼び出すと、そのようなツールは実行内容のプレビューだけを返し、何も変更しません。承認後、アシスタントは confirm: true を指定して呼び出しを繰り返します。

モデルは最初の呼び出しでも confirm: true を設定できます。その場合もサーバーはプレビューを計算して結果とともに返しますが、人間が同意したことを証明できるのはクライアントの承認プロンプトだけです。これらのツールはすべて destructiveHint を設定しているため、破壊的な呼び出しの前に確認を求めるクライアントは、ここでも確認を求めます。

クイックスタート

要件： Node.js 22 以降、お使いのマシンから接続できる Keycloak サーバー（Keycloak 24.0～26.8 でテスト済み）、および MCP クライアント。

1. Keycloak を準備する（3 ステップ）

管理するレルム（ここでは demo）で、次の操作を行います。

1. クライアント mcp-admin を作成し、クライアント認証 を オン にして、サービスアカウントのロール のみを有効にします（標準フロー と ダイレクトアクセスグラント はオフにします）。
2. ロールを割り当てます。 クライアントの サービスアカウントのロール タブで、realm-management のクライアントロールを割り当てます。まず読み取り専用で試す場合は、view-users、query-users、query-groups、view-realm を割り当てます。
3. シークレットをコピーします。 クライアントの 認証情報 タブからコピーしてください。

Admin Console のクリック手順、kcadm.sh コマンド、ローカルの Docker Keycloak を使った詳しい手順は、docs/getting-started.md をご覧ください。

2. MCP クライアントを設定する

Claude Code の例（他のクライアントについては docs/clients.md をご覧ください）：

claude mcp add --transport stdio \
  --env KEYCLOAK_URL=https://keycloak.example.com \
  --env KEYCLOAK_AUTH_REALM=demo \
  --env KEYCLOAK_CLIENT_ID=mcp-admin \
  --env KEYCLOAK_CLIENT_SECRET="$KEYCLOAK_CLIENT_SECRET" \
  keycloak -- npx -y keycloak-model-context-protocol@1

または JSON の例（Claude Desktop、claude_desktop_config.json）：

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "keycloak-model-context-protocol@1"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_AUTH_REALM": "demo",
        "KEYCLOAK_CLIENT_ID": "mcp-admin",
        "KEYCLOAK_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}

3. 最初の質問をする

アクセスできるレルムを一覧表示し、レルム demo の最初の 10 人のユーザーを表示してください。

回答が得られれば完了です。回答が得られない場合は、docs/troubleshooting.md をご覧ください。

設定

すべての設定は環境変数で指定します。必須なのは KEYCLOAK_URL と、いずれか一組の認証情報のみです。

変数	デフォルト	用途
KEYCLOAK_URL	(required)	Keycloak サーバーのベース URL
KEYCLOAK_AUTH_REALM	master	ログインアカウントまたはクライアントが存在するレルム
KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET	none	client_credentials ログイン（推奨）
KEYCLOAK_USERNAME / KEYCLOAK_PASSWORD	none	パスワードグラントによるログイン（クライアントのデフォルトは admin-cli）
KEYCLOAK_GRANT_TYPE	auto	client_credentials または password。設定内容から自動判定
KEYCLOAK_MCP_TOOLSETS	core,groups,roles	有効にするツールセット、または all
KEYCLOAK_MCP_READ_ONLY	false	読み取り専用ツールのみを登録
KEYCLOAK_MCP_REALMS	all	対象レルムの許可リスト（カンマ区切り）
KEYCLOAK_MCP_ALLOW_MASTER_WRITE	false	master レルムでの書き込みツールを許可
KEYCLOAK_MCP_REQUIRE_CONFIRMATION	true	破壊的な操作や機密性の高いツールには confirm: true が必要です
KEYCLOAK_MCP_TIMEOUT_MS	30000	Keycloak リクエストの HTTP タイムアウト
KEYCLOAK_MCP_LOG_LEVEL	info	debug、info、warn、error（stderr）

使用例、検証ルール、ツールとロールの対応表を含む完全なリファレンスは、docs/configuration.md をご覧ください。

ツールセットとツール

ツールの名前は <domain>_<verb> 形式です。KEYCLOAK_MCP_TOOLSETS を設定しない限り、デフォルトのツールセットのみが有効になります。読み取り専用モードでは、read 種別のツールのみが登録されます。

ツールセット	デフォルト	ツール
core	yes	realm_list、realm_get、user_search、user_get、user_create（機密）、user_update（機密）、user_delete（破壊的）、user_send_actions_email（機密）
groups	yes	group_list、group_members_list、user_group_add（機密）、user_group_remove（破壊的）
roles	yes	role_list、user_roles_list、user_role_assign（機密）、user_role_revoke（破壊的）
clients	no	client_list、client_get
sessions	no	user_sessions_list、user_logout（破壊的）
events	no	event_list、admin_event_list
security	no	user_brute_force_status、user_brute_force_unlock（機密）

各ツールの詳細（パラメーター、出力、必要なロール）：docs/tools-reference.md。

プロンプトとリソース

プロンプトは、ツールを使って実行するガイド付きワークフローです。クライアントのプロンプトピッカーに表示されます（Claude Code ではスラッシュコマンドとして表示されます）。realm 引数は自動補完されます。

プロンプト	内容
onboard_employee	ユーザーを作成し、グループとロールを追加して、歓迎メールを送信します
offboard_employee	退職する従業員を確認し、セッションを終了してアカウントを無効化します（削除はしません）
audit_realm_security	優先度付きの指摘事項を含む、読み取り専用のセキュリティレビューを行います
investigate_failed_logins	何も変更せずに、ログイン失敗とロックアウトの状態を分析します

リソースは、同じレルム許可リストでフィルタリングされる読み取り専用の JSON ドキュメントです。

URI	内容
keycloak://realms	アクセス可能なレルムの名前
keycloak://realms/{realm}	レルム設定の安全なサブセット
keycloak://realms/{realm}/security-summary	ブルートフォース攻撃、パスワードポリシー、SSL、OTP、イベントフラグ、クライアント公開件数（シークレットは含みません）
keycloak://realms/{realm}/users/{userId}	1 人のユーザーの基本フィールド（属性と認証情報は含みません）

セキュリティ

• まず最小権限を適用してください。 1 つのレルムにスコープを限定し、必要な realm-management ロールのみを付与したサービスアカウントクライアントを使用してください。ロールの一覧は docs/configuration.md を参照してください。
• すべての変更には確認が必要です（KEYCLOAK_MCP_REQUIRE_CONFIRMATION=true）。破壊的な操作や機密性の高いツールでは、まずプレビューが表示されます。複合ロールや親グループを通じた場合も含む管理者権限の付与、管理者権限を持つアカウントのプロフィール変更およびアクションメールの送信、サーバー自身のアカウントに対する変更では、KEYCLOAK_MCP_REQUIRE_CONFIRMATION=false にしても無効にならない確認が必要です。サーバー自身のアカウントに対するロールやグループの付与、プロフィール変更、アクションメールの送信は拒否されます。
• アカウント乗っ取り対策： メールアドレスを変更すると、明示的に指定されない限り未確認としてマークされます。アクションメールのリンクの有効期間は最長 24 時間です。プレビューには、送信先のメールアドレスと対象アカウントが管理者権限を持つかどうかが表示されます。
• 影響範囲の制限： KEYCLOAK_MCP_READ_ONLY、KEYCLOAK_MCP_REALMS、および master の書き込み保護（デフォルトでは無効）。
• 出力やログにシークレットを含めません。 認証情報は stderr 上でマスクされます。ツールがクライアントシークレット、ユーザー認証情報、属性を返すことはありません。
• プロンプトインジェクション： Keycloak から取得した名前や説明はデータとして扱ってください。付属のプロンプトでは、そのように明示されています。書き込みツールが不要な場合は、無効にしておいてください。

脅威モデル、セキュリティ強化チェックリスト、脆弱性の報告方法については、docs/security.md と SECURITY.md を参照してください。

プロンプトの例

• 「表示できるレルムを教えてください。レルム demo の設定を見せてください。」
• 「demo 内で、メールアドレスが @example.com で終わり、無効になっているユーザーをすべて探してください。」
• 「demo にユーザー jdoe（Jane Doe、[email protected]）を作成し、グループ engineering に追加して、パスワード設定用のメールを送信してください。」
• 「グループ ops には誰が所属していますか。また、複合ロールを含めて alice が持つロールを教えてください。」
• 「demo に対して audit_realm_security プロンプトを実行してください。」 (監査を完全に行うには、clients と events のツールセットが必要です)
• 「昨夜、多数のログインに失敗しました。レルム demo を調査してください。」
• 「demo の bob のアカウントを整理してください。セッションを終了し、アカウントを無効にしてください。」

ドキュメント

ドキュメント	内容
docs/getting-started.md	ローカルの Keycloak、サービスアカウントの設定、初回実行、MCP Inspector
docs/configuration.md	環境変数リファレンス、ロール一覧、ロールプロファイル、TLS
docs/clients.md	Claude Desktop、Claude Code、VS Code、Cursor、汎用クライアント
docs/tools-reference.md	すべてのツールの詳細
docs/security.md	脅威モデルとセキュリティ強化
docs/troubleshooting.md	症状、原因、解決策
docs/architecture.md	コンポーネント、フロー、設計上の判断
CHANGELOG.md	リリースノート

0.x からのアップグレード

バージョン 1.0 ではデフォルト設定が変更されています。認証情報が必須となり（admin/admin へのフォールバックはありません）、破壊的な操作を行うツールでは確認が求められます。また、ツール名は <domain>_<verb> に変更されました（例：create-user は user_create に、delete-user は user_delete に変更）。従来の KEYCLOAK_ADMIN と KEYCLOAK_ADMIN_PASSWORD 変数も引き続き使用できますが、非推奨です。移行ガイドを参照してください。

Contributing and license

Contributions are welcome. See CONTRIBUTING.md and the Code of Conduct. Released under the MIT License.