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 サインインを使用する staging レルムを作成して。"

• "先週、本番レルムに追加されたのは誰？"

• "管理者イベントを Datadog webhook に転送する SIEM 転送先を設定して。"

Related MCP server: MCP Authentik

認証と安全性

• ホステッド HTTP（OAuth、設定する認証情報は不要）。 クライアントをヘッダーなしで https://mcp.skycloak.io に向けます。サーバーは 401 を返し、/.well-known/oauth-protected-resource にある RFC 9728 メタデータへのポインターを示します。クライアントは Skycloak のログインレルムに対してブラウザーの認可コードフローを実行し、受け取ったアクセストークンは、セッションが使用する短期間有効なワークスペーススコープの API キーと交換されます。このキーは 1 時間有効で、自動的に更新されます。クライアント設定には何も保存されません。

• ホステッド HTTP（API キー）。 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 を表示します。

ツール

129 個のツール: 読み取り専用 58 個と書き込み 71 個です。読み取り専用ツールは常に利用できます。ホステッドサーバーでは書き込みツールも登録され、認証情報のスコープによって制御されます。ローカルバイナリは --allow-writes を付けて起動した場合のみ登録します。

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

規約: 破壊的なツール（delete_*、uninstall_extension、cancel_cluster_upgrade）には confirm=true が必要です。create_cluster は非同期です。get_cluster をポーリングしてクラスターが available になるまで待ちます。create_domain は顧客が作成する必要があるDNSレコードを返します。verify_domain はDNSチェックをトリガーします。set_theme_assignment はKeycloakテーマタイプごとにカスタムテーマを有効にします（空文字列でビルトインのデフォルトにリセット）。update_cluster_security はCAPTCHA設定を変更しません。レルムのインポート/エクスポートは1つのレルムの設定を移動し、クラスター全体のデータベースをダンプする create_export とは別のものです。どちらも非同期で、レルムアーカイブは常に暗号化されているため、エクスポート時に使用したパスワードが再インポート時に必要です。レルムは既存のエクスポート（source_export_id）から直接インポートするか、アップロードされたアーカイブ（create_realm_import_upload_url、PUT、次に upload_s3_key）からインポートできます。インポートはレルムを作成し、上書きではなく名前の衝突を拒否します。また、ユーザーと認証情報を伴うため confirm=true が必要です。

接続

ホスト型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 セッションが動作するワークスペースを選択します。これは複数のワークスペースに所属している場合にのみ必要です。単一のワークスペースの場合はサーバーが自動的に選択します。複数に所属していて名前を指定しない場合、接続は失敗し、そのリストを示すメッセージが表示されます。

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 を設定してください。ドキュメントには scopes_supported として openid profile email もリストされ、WWW-Authenticate チャレンジはそれらを scope パラメータとして繰り返すため、どちらかを読むクライアントはレルムにそれらを要求します。openid は必須です。トークン交換によりダッシュボードが Keycloak のユーザー情報エンドポイントを呼び出し、Keycloak は openid なしで付与されたトークンを拒否するためです。openid なしで到着したトークンは、成功できない交換に持ち込まれることなく、検証時に 401 とチャレンジで拒否されるため、以前の付与をまだ保持しているクライアントは再試行を停止して再サインインします。発行者またはダッシュボード変数のいずれかを空白にすると、OAuth は完全にオフになり、サーバーは API キーのみを要求するようになります。

起動時には、解決された配線（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 など）が追加されます。交換失敗では、ダッシュボードのステータスと呼び出されたホストが追加されます。呼び出し元は、トークンが検証された後にそのサブジェクトとして表示され、資格情報として表示されることはありません。アクセストークン、Authorization ヘッダー、および生成された API キーは決してログに記録されません。

設定

コマンド: init（ブラウザサインイン）、run（サーブ）、logout（保存されたキーを削除）。init は --workspace <id>、--allow-writes、--allow-credentials、--ttl-days（デフォルト 90）を受け入れます。

開発

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 クライアントは、oapi-codegen を使用して Skycloak OpenAPI 仕様から生成されます。

API との同期を維持する

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

配布

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

セキュリティ

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

貢献者

Skycloak で Guilliano Molaire、Neville Omangi、Aphilas によって構築されました。リポジトリの履歴は公開時にスカッシュされたため、コミットログは誰が何を書いたかを反映していません。

ライセンス

Apache-2.0。internal/apiclient/openapi.yaml の OpenAPI 記述は Skycloak プラットフォーム API から生成されたもので、(c) Skycloak に帰属します。クライアントの生成と検証のためにここに含まれています。NOTICE を参照してください。