Skycloak

skycloak-mcp

Skycloak（マネージド Keycloak）向けの公式Model Context Protocolサーバーです。任意の MCP クライアント（Claude Desktop、Claude Code、Cursor）から、クラスター、レルム、アプリケーション、SSO を管理できます。

ステータス： 初期リリースです。ツールの対応範囲は拡大中です。利用可能な機能については変更履歴をご覧ください。

クイックスタート

claude mcp add --transport http skycloak https://mcp.skycloak.io

API キーもクライアント ID も設定も不要です。ブラウザーが開き、Skycloak にサインインすると、ツールが表示されます。ストリーミング可能な HTTP に対応する MCP クライアントであれば、同じように動作します。URL を渡すだけで、それ以外は何も必要ありません。

次のように頼んでみてください。

• 「アップグレードが遅れている Keycloak クラスターを教えてください。」
• 「EU クラスターに、Google と GitHub のサインインを設定したステージング用レルムを作成してください。」
• 「過去 1 週間に本番レルムへ追加されたユーザーは誰ですか？」
• 「管理者イベントを Datadog の Webhook に転送する SIEM の送信先を設定してください。」

認証と安全性

• OAuth を使用するホスト型 HTTP（設定する認証情報はありません）。 クライアントを https://mcp.skycloak.io にヘッダーなしで接続します。サーバーは RFC 9728 のメタデータへの参照先 /.well-known/oauth-protected-resource とともに 401 を返します。クライアントは Skycloak ログインレルムに対してブラウザー認可コードフローを実行し、取得したアクセストークンは、セッションで使用する有効期間の短いワークスペーススコープの API キーと交換されます。このキーの有効期間は 1 時間で、自動的に更新されます。クライアント設定には何も保存されません。
• API キーを使用するホスト型 HTTP。 Skycloak ダッシュボードでキーを作成し、Authorization: Bearer <key>（または API-Key: <key>）として送信します。各リクエストにはそれぞれの認証情報が含まれ、その認証情報のワークスペースとしてのみ動作します。サーバーはセッション状態を保持しないため、リクエストが別の呼び出し元の状態を引き継ぐことはありません。キーは使用前に検証されません。権限の判断は Skycloak API が行うため、無効なキーは接続時ではなく、最初のツール呼び出し時に 401 として通知されます。
• ツールはロールに応じて表示されます。 OAuth では、セッションのスコープで許可されるツールだけが一覧に表示されるため、読み取り専用のワークスペースメンバーには、呼び出すと 403 を返す書き込みツールは表示されません。API キーでは、キーのスコープをサーバーが確認できないため、すべてのツールが登録されます。許可されていない呼び出しは、API からの 403 として通知されます。
• ローカル stdio。 skycloak-mcp init を実行し、ブラウザーで承認します（OAuth 2.0 デバイス認可フロー）。ワークスペーススコープの API キーが発行され、オペレーティングシステムのキーチェーンに保存されます。また、デフォルトのワークスペースが自動的に検出されます（別のワークスペースを選ぶには --workspace <id> を渡します）。skycloak-mcp logout を実行すると、保存されたキーが削除されます。
• ヘッドレス／CI。 SKYCLOAK_API_KEY 環境変数を設定すると（キーは Skycloak ダッシュボードで作成します）、ブラウザーを使わずに済みます。この設定は常にキーチェーンのキーより優先されます。
• 書き込みの可否はフラグではなく、認証情報で決まります。 https://mcp.skycloak.io のホスト型サーバーでは書き込みが有効です。実際に変更できる範囲はキーのスコープとワークスペースでのロールによって制限されます。ツール一覧に何が表示されていても、読み取り専用メンバーは何も変更できません。URL に ?readonly=true を追加すると、セッションで読み取り専用のツールのみが表示されます。ローカルバイナリはその逆で、--allow-writes を付けて起動しない限り、書き込みツールは登録されません。
• クラスター認証情報はオプトインです。 get_cluster_credentials はクラスターの Keycloak 管理者認証情報を返します。キーを持つアシスタントにはその情報が見えるため、init ではこのスコープをデフォルトで要求しません。このスコープを含むキーを使用してください。ダッシュボードでキーを作成するか、stdio から skycloak-mcp init --allow-credentials でサインインします。このスコープがない場合、ツールは両方の方法を説明する 403 を返します。
• 破壊的なツールには確認が必要です。 たとえば、レルムの削除には confirm=true 引数を明示的に指定する必要があります。
• リクエストは Skycloak のプランに応じてレート制限されます。429 応答の場合、サーバーは Retry-After を通知します。

ツール

137 個のツール：読み取り専用が 60 個、書き込みが 77 個です。読み取り専用ツールは常に使用できます。ホスト型サーバーでは書き込みツールも登録され、認証情報のスコープによって制限されます。ローカルバイナリでは、--allow-writes を付けて起動した場合にのみ書き込みツールが登録されます。

ツール名には skycloak_ プレフィックスが付いていますが、以下の表では省略しています。そのため、クライアントでの list_clusters は skycloak_list_clusters となります。

Area	Read-only	Write (--allow-writes)
Clusters	list_clusters, get_cluster, list_cluster_locations, list_cluster_types, list_cluster_features, list_cluster_versions, list_cluster_upgrades, get_cluster_upgrade_path, get_cluster_credentials, get_cluster_insights, get_cluster_maintenance_window	create_cluster, update_cluster, delete_cluster, cancel_cluster_upgrade, restart_cluster_instances, set_cluster_maintenance_window, delete_cluster_maintenance_window
Edge security	get_cluster_security, list_cluster_captcha_domains	update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realms	list_realms, get_realm	create_realm, update_realm, delete_realm
Applications	list_applications, get_application, list_application_roles, list_application_sessions	create_application, update_application, delete_application, assign_application_role, remove_application_role, rotate_application_secret
Identity providers	list_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidc	create_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider
Users, roles & groups	list_realm_users, get_realm_user, list_realm_roles, get_realm_role, list_realm_groups, get_realm_group, list_realm_group_members, list_user_roles, list_user_groups	create_realm_user, update_realm_user, delete_realm_user, create_realm_role, update_realm_role, delete_realm_role, create_realm_group, update_realm_group, delete_realm_group, assign_realm_user_role, remove_realm_user_role, add_realm_user_to_group, remove_realm_user_from_group
Custom domains	list_domains, get_domain, list_domain_routes, get_domain_route	create_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route
Branding & themes	list_themes, get_theme, get_theme_assignment, get_client_theme_assignment, get_login_branding, get_email_branding, download_theme_content, get_theme_settings	set_theme_assignment, set_client_theme_assignment, update_theme, update_theme_content, update_theme_settings, delete_theme, upsert_login_branding, delete_login_branding, upsert_email_branding, delete_email_branding
Extensions	list_extensions, list_cluster_extensions	install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTP	get_smtp	upsert_smtp, delete_smtp, test_smtp
Exports & logs	list_exports, get_export, get_logs, get_security_logs, query_events	create_export, delete_export, export_cluster_events
Realm import & export	get_realm_export, get_realm_import	create_realm_export, create_realm_import, create_realm_import_upload_url
SIEM	list_siem_destinations, get_siem_destination	create_siem_destination, update_siem_destination, delete_siem_destination, test_siem_destination
Webhooks	list_webhook_event_types, list_webhook_subscriptions, get_webhook_subscription	create_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription

規則： 破壊的なツール（delete_*、uninstall_extension、cancel_cluster_upgrade、update_theme_content、update_theme_settings、restart_cluster_instances）には confirm=true が必要です。update_theme_settings は、ワークスペースで exact_theme_names を有効または無効にします。呼び出し元の API キーはワークスペースのオーナーまたは管理者向けに発行されている必要があり、そうでない場合は themes:write があっても 403 が返されます。有効にすると、既存のテーマはバックグラウンドで実際に配信される正確な名前へ移行されます。正確な名前を維持したままコンテンツが置き換えられたテーマは、そのクラスターの Keycloak インスタンスを restart_cluster_instances で再起動するまで、get_theme／list_themes／update_theme_content で restart_required: true を返します。再起動はすぐに適用せず、クラスターのメンテナンスウィンドウまで延期される場合があり、その場合は deferred: true と、判明していれば next_window で示されます。create_cluster は非同期です。クラスターが available になるまで get_cluster をポーリングしてください。create_domain は顧客が作成する必要のある DNS レコードを返し、verify_domain は DNS チェックを開始します。set_theme_assignment は Keycloak のテーマタイプごとにカスタムテーマを有効にします（空の文字列を指定すると、組み込みのデフォルトに戻ります）。update_theme_content は、テーマのアーカイブ（content_base64 内の base64 ZIP または Keycloakify JAR）をその場で置き換え、テーマの ID、名前、レルム、およびアプリケーションへの割り当てを維持します。そのため、テーマを編集する際に削除して再アップロードする必要はありません。上書きしたアーカイブは復元できないため、confirm=true が必要です。update_theme で変更できるのは、引き続き名前、説明、バージョンのみです。この呼び出し方法については、docs/theme-content-update.md を参照してください。update_cluster_security は CAPTCHA の設定を変更しません。レルムのインポート／エクスポートでは、単一レルムの設定を移行します。クラスター全体のデータベースをダンプする create_export とは別の機能です。どちらも非同期で、レルムのアーカイブは常に暗号化されるため、エクスポート時に使用したパスワードは、再度インポートする際にも必要です。レルムは既存のエクスポート（source_export_id）から直接インポートするか、アップロードしたアーカイブ（create_realm_import_upload_url、PUT、その後 upload_s3_key）からインポートできます。インポートするとレルムが作成され、同名のレルムがある場合は上書きせず拒否されます。ユーザーと認証情報も含まれるため、confirm=true が必要です。

クラスターのロケーション： create_cluster の location と、list_clusters、get_cluster、list_cluster_locations が返す location は、大文字・小文字を問わず us（米国東部）、us-west（米国西部）、ca（カナダ）、eu（ヨーロッパ）、au（オーストラリア）のいずれかです。us は常に米国東部を意味します。us-west を利用できるのは、そのアクセス権が付与されているワークスペースのみです。list_cluster_locations は、ワークスペースで available に設定されているすべてのロケーションを一覧表示します。利用できないロケーションにクラスターを作成すると、API は 400「location not available」を返します。

プロンプト

8 つのプロンプトが、このツール群を使い始めるための手がかりになります。クライアントではスラッシュコマンドまたは推奨アクションとして表示され、それぞれが引数（realm、cluster、時間範囲）を受け取り、適切なツールを適切な順序で使うようモデルを導きます。

プロンプト	内容
audit_self_registration	1 つまたはすべてのクラスターを対象に、自己登録がまだ許可されているすべての realm を特定します
review_upgrades	Keycloak のバージョンが古いクラスターを見つけ、アップグレード手順を提示します
triage_failed_logins	realm の最近のログイン失敗を取得し、送信元 IP ごとに分類します
review_identity_providers	realm の SSO 接続を一覧表示し、指定された接続が有効になっているか確認します
review_admin_changes	realm で最近行われた変更について、ログインとセキュリティの設定を中心に、誰が何を変更したかを表示します
provision_environment	クラスターを作成し、realm を追加して、アイデンティティプロバイダーを接続し、各手順を確認します
set_up_custom_domain	カスタムドメインを追加し、正確な DNS レコードを提示して検証したうえで、realm にルーティングします
rotate_client_secret	影響範囲を事前に明示して、アプリケーションのクライアントシークレットを再生成します

プロンプトにも、それが指定するツールと同じアクセス制御が適用されます。書き込みツールを参照する 3 つのプロンプトは、対応する書き込みツールを呼び出せるセッションにのみ提示され、その指示では変更を行う前にユーザーへ確認するようモデルに伝えます。破壊的なツールに対する confirm=true の要件も、引き続き適用されます。

スキル

プロンプトが出発点となるのに対し、スキルはモデルが必要に応じて読み込む、実運用向けの包括的な手順書です。サーバーには、草案段階の SEP-2640 Skills extension を通じて提供される 4 つのスキルが含まれています。capabilities で io.modelcontextprotocol/skills を宣言し、skills/list と skills/get に応答します。また、各 SKILL.md を通常のリソースとして skill://<name>/SKILL.md で提供し、一覧エントリーには sha256 ダイジェストを含めます。OpenAI のプラグインディレクトリは、まさにこの形式でスキルをインポートします。

スキル	内容
auth-incident-triage	「ユーザーがログインできない」問題を切り分けます。イベント、WAF ログ、クラスターの健全性を使って、プラットフォームの障害、攻撃、設定変更を区別します。読み取り専用です
enterprise-sso-rollout	エンタープライズ IdP を realm にエンドツーエンドで接続します。issuer の検証、上流アプリケーションの登録、ブローカーの設定、接続テスト、実際のログインイベントを使った検証を行います
keycloak-migration-doctor	サポートで実際に確認される阻害要因（スクリプトポリシー、従来の /auth パス、部分エクスポートの想定）を踏まえて、Keycloak のエクスポート、インポート、移行の事前確認を行います。また、一般的なダッシュボードの通知ではなく、実際の error_message を読み取って失敗したジョブを診断します
keycloak-upgrade-readiness	バージョンの差異を評価し、新しい Keycloak バージョンによって何が影響を受けるか（拡張機能、テーマ）を特定したうえで、ロールバック計画としてエクスポートを用意し、環境間での段階的な展開手順を立てます

スキルにも、それが指定するツールと同じアクセス制御が適用されます。書き込みツールを中心とする 3 つのワークフローは読み取り専用セッションには提示されず、スコープが設定されたセッションには、実際に利用できるツールだけを使うスキルが提示されます。ソースは internal/tools/skills/ にあり、スキルごとにディレクトリが分かれています。標準の Agent Skills 形式なので、そのままローカルのスキルディレクトリにコピーしても使用できます。

接続

ホスト型 HTTP では、最も簡単なのは OAuth です。認証情報は必要ありません。

claude mcp add --transport http skycloak https://mcp.skycloak.io

最初の呼び出しでブラウザーが開き、Skycloak のログインページで承認すると、ツールが表示されます。複数のワークスペースに所属している場合は、使用するワークスペースを指定してください。

claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"

または、Skycloak ダッシュボードで API キーを作成し、MCP クライアントがベアラートークンとして送信するように設定してください。

claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"

これにより、.claude.json に以下が追加されます。

{
  "mcpServers": {
    "skycloak": {
      "type": "http",
      "url": "https://mcp.skycloak.io",
      "headers": {
        "Authorization": "Bearer sk_sc_XXX"
      }
    }
  }
}

ローカル stdio の場合は、一度サインインしてから、クライアントの接続先を skycloak-mcp run に設定してください。

skycloak-mcp init        # one-time browser sign-in; stores a key in your keychain

Claude Desktop / Cursor（ローカル、stdio）：

{
  "mcpServers": {
    "skycloak": {
      "command": "skycloak-mcp",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Claude Code：

claude mcp add skycloak -- skycloak-mcp run --transport stdio

ヘッドレス環境／CI（ブラウザーなし）の場合は、init を省略してキーを渡してください。設定に "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } を追加するか、claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio を実行します。

変更を行う場合にのみ --allow-writes を追加してください（skycloak-mcp init --allow-writes でサインインするか、書き込み権限を持つキーを使用してください）。

ホスト型 HTTP の URL に ?readonly=true を追加すると、その HTTP セッションでは読み取り専用ツールのみが公開されます。?readonly=false を追加すると、書き込み可能なツールがリクエストされます。クエリパラメーターのデフォルト値は false ですが、書き込みツールが登録されるのは、サーバーが --allow-writes を指定して起動された場合のみです。

?workspace=<uuid> を追加すると、OAuth セッションで使用するワークスペースを選択できます。これは複数のワークスペースに所属している場合のみ必要です。ワークスペースが1つの場合はサーバーが自動的に選択します。複数のワークスペースに所属していて、どれも指定しない場合は、それらの一覧を示すメッセージとともに接続が失敗します。

HTTP トランスポートの実行

skycloak-mcp run --transport http --http-addr :8080

独自の認証情報は必要ありません。呼び出し元がリクエストごとに認証情報を渡すため、デプロイ時に何かを注入する必要はありません。GET /healthz と GET /readyz は認証なしで利用でき、プロセスが稼働中であることだけを報告します。これらのエンドポイントは意図的に Skycloak API の応答を確認しないため、上流の一時的な障害によってすべてのレプリカのプローブが一斉に失敗することはありません。サーバーはセッション状態を保持しないため、レプリカにセッションアフィニティは不要で、自由にスケールしたり、再起動したりできます。SIGTERM を受信すると、新しい接続を停止し、処理中の呼び出しが完了するまで待機します。

OAuth パスは、SKYCLOAK_ISSUER と SKYCLOAK_DASHBOARD_URL が設定されている場合に有効になります。これらはデフォルトで設定されています。その場合、GET /.well-known/oauth-protected-resource は認証なしで提供され、認可サーバーとしてレルムを指定します。resource の値は、SKYCLOAK_PUBLIC_URL が設定されていればその値が使われ、設定されていなければリクエスト自体の Host とスキームから取得されるため、Ingress の背後に単一ホストでデプロイする場合、追加の設定は不要です。スキームは X-Forwarded-Proto があればその値を使い、なければループバックホスト以外では https がデフォルトになります。これは TLS が上流で終端されるためで、http:// の識別子を公開すると、クライアントが接続した URL と一致しなくなるためです。Ingress が Host を書き換える場合は、SKYCLOAK_PUBLIC_URL を設定してください。このドキュメントは openid profile email も scopes_supported として列挙し、WWW-Authenticate チャレンジでも scope パラメーターとして同じ値を指定するため、どちらを読み取ったクライアントもレルムにこれらのスコープを要求します。トークン交換時にダッシュボードが Keycloak の userinfo エンドポイントを呼び出し、openid を付与せずに発行されたトークンは Keycloak に拒否されるため、openid は必須です。検証時にこのスコープを含まないトークンは、成功しないトークン交換へ進められるのではなく、チャレンジを伴う 401 で拒否されます。そのため、以前の認可を保持しているクライアントもリトライを停止し、再度サインインします。発行者またはダッシュボードの変数を空にすると、OAuth は完全に無効になり、サーバーは API キーのみを要求するようになります。

OPENAI_APPS_CHALLENGE_TOKEN は、OpenAI のプラグインディレクトリのドメイン検証トークンを /.well-known/openai-apps-challenge でプレーンテキストのみとして提供します。設定されていない場合、このルートは登録されず、そのパスは 404 を返します。

起動時には、解決された設定（oauth=、issuer=、dashboard=、public_url=、endpoint=、allow_writes=）を 1 行に記録するため、再デプロイせずに設定ミスを見つけられます。OAuth パスで拒否されたリクエストはすべて、失敗した段階（verify、exchange、scopes）、呼び出し元に返されたステータス、根本原因となるエラーを示す 1 行のログに記録されます。検証に失敗した場合は、トークンを拒否したチェック（expired、wrong_issuer、bad_signature、unknown_key_id、wrong_token_type、no_openid_scope など）が追加されます。トークン交換に失敗した場合は、ダッシュボードのステータスと呼び出したホストが追加されます。トークンの検証後は、呼び出し元はトークンの subject として記録され、認証情報として記録されることはありません。アクセストークン、Authorization ヘッダー、発行された API キーがログに記録されることはありません。

設定

環境変数	デフォルト
SKYCLOAK_API_KEY	なし（stdio では省略可能です。HTTP クライアントは代わりに API-Key ヘッダーを指定します）
SKYCLOAK_ENDPOINT	https://api.skycloak.io
SKYCLOAK_API_VERSION	現在の API バージョン
SKYCLOAK_ISSUER	https://login.app.skycloak.io/realms/skycloak（CLI のサインイン、および HTTP トランスポートがトークンの検証に使用する認可サーバー）
SKYCLOAK_CLIENT_ID	skycloak-mcp（CLI のデバイスフローのみ）
SKYCLOAK_DASHBOARD_URL	https://app.skycloak.io（CLI キーと HTTP セッションキーを発行します）
SKYCLOAK_PUBLIC_URL	なし（リクエストごとに導出されます。イングレスによって Host が書き換えられる場合は設定してください）
OPENAI_APPS_CHALLENGE_TOKEN	/.well-known/openai-apps-challenge で OpenAI のプラグインディレクトリ検証トークンを提供します。未設定の場合、このパスは 404 を返します。

コマンド：init（ブラウザーでサインイン）、run（サービスを起動）、logout（保存済みのキーを削除）。init では、--workspace <id>、--allow-writes、--allow-credentials、--ttl-days（デフォルトは 90）を指定できます。

フラグ	デフォルト	説明
--transport	stdio	stdio または http
--http-addr	:8080	HTTP トランスポートのリッスンアドレス
--allow-writes	false	stdio で変更を伴うツールを有効にし、readonly=false の HTTP セッションで書き込みツールの登録を許可します

開発

make build      # build the server binary
make test       # unit tests
make run        # run on stdio for local testing
make inspector  # MCP Inspector against the local binary
make lint       # golangci-lint
make generate   # regenerate the API client from the OpenAPI spec

internal/apiclient 配下の API クライアントは、Skycloak OpenAPI 仕様から oapi-codegen で生成されています。

API との同期を保つ

internal/apiclient のクライアントは、internal/apiclient/openapi.yaml から oapi-codegen で生成されています。更新するには make generate を実行してください。コミット済みの生成コードと仕様に差異がある場合、CI は失敗します。リクエストは Retry-After に応じたバックオフで、429／5xx の場合に再試行されます。

配布

各タグのリリース時に GitHub バイナリと ghcr.io/sky-cloak/skycloak-mcp コンテナーイメージとして配布し、MCP Registry に io.skycloak/skycloak-mcp として公開しています。ほとんどの方は、どちらも必要ありません。ホスト型サーバーはインストール不要です。

セキュリティ

脆弱性は非公開で報告してください。SECURITY.md をご覧ください。

コントリビューター

Skycloak にて、Guilliano Molaire、Neville Omangi、Aphilas が開発しました。公開時にリポジトリの履歴を 統合したため、コミットログから誰が何を書いたかは分かりません。

ライセンス

Apache-2.0。internal/apiclient/openapi.yaml の OpenAPI 記述は Skycloak プラットフォーム API から生成され、Skycloak の著作物（©）です。クライアントの生成と検証に使用できるよう、ここに含めています。NOTICE をご覧ください。