Crossplane

crossplane-mcp-server

AI アシスタントが Crossplane のコントロールプレーンを理解できるようにする、Model Context Protocol サーバーです。

アシスタントに 「管理対象リソースはいくつあり、何か問題は起きていますか？」 と尋ねると、推測ではなく、実際のコントロールプレーンから各失敗の理由も含めて回答します。

> Why is the app-db claim not ready?

  crossplane_diagnose(kind="PostgreSQLInstance", name="app-db")

  PostgreSQLInstance app-db is NOT READY.

  Verdict: Instance/app-db-rds is the deepest failure: InvalidParameterValue:
  the instance class db.t2.mega does not exist

  Root causes (deepest failing resources):
  KIND       NAME          READY   SYNCED   REASON          DETAIL
  Instance   app-db-rds    False   False    ApplyFailure    InvalidParameterValue...

  Control plane checks:
  CHECK         STATE   DETAIL
  composition   OK      Composition "postgres-aws" exists.
  providers     OK      all 3 provider(s) are Installed and Healthy

  Fix the instanceClass field in your Composition and the claim will reconcile.

このサーバーはデフォルトで読み取り専用です。作成・更新を行うツールは、--read-only=false を指定して起動しない限り登録されないため、クライアントからそれらのツールを参照することも、ましてや呼び出すこともできません。どちらのモードでも削除はできません。書き込みを有効にすると、同じアシスタントからプラットフォーム API を使ってプロビジョニングできます。

> Create a small Postgres database called orders-db.

  crossplane_database_create(name="orders-db", engine="postgresql", size="small")

  Created PostgreSQLInstance default/orders-db on kind-crossplane.

  apiVersion: demo.crossplane.io/v1alpha1
  kind: PostgreSQLInstance
  metadata:
    name: orders-db
    namespace: default
  spec:
    parameters:
      engine: postgresql
      size: small
      version: "16"

  Next: provisioning is asynchronous. Call crossplane_resource_tree with
  {"kind":"PostgreSQLInstance","name":"orders-db"} to watch it come up.

ここには Kubernetes の Kind は出てきません。ツールはこのコントロールプレーンが提供するプラットフォーム API を見つけ、XRD が宣言するスキーマを読み取り、その内容を埋めました。クラウドアカウントなしで試せるコントロールプレーンについては、examples/demo をご覧ください。

目次

• 汎用 Kubernetes MCP サーバーではだめなのですか？
• クイックスタート
• インストール
• クライアント設定
• ツール
• 読み取り専用モードと書き込みモード
• プロンプト
• ツールを直接呼び出す
• 設定
• 複数のコントロールプレーン
• クラスター内での実行
• 必要な RBAC
• コントリビューション
• セキュリティ
• ライセンス

汎用 Kubernetes MCP サーバーでは不十分な理由

汎用の Kubernetes MCP サーバーでも、Crossplane コントロールプレーン上のすべてのオブジェクトにアクセスできます。Crossplane リソースも Kubernetes リソースであり、apiVersion と kind を指定した汎用の resources_list を実行すれば、XRD も問題なく取得できます。アクセス自体は、これまで問題ではありませんでした。

問題は、それらが何を意味するのかを把握しておらず、問題なく削除してしまうことです。

	汎用 Kubernetes MCP	このサーバー
Crossplane CRD へのアクセス	はい	はい
claim から、作成されたインフラストラクチャをたどる	いいえ。オブジェクトを返すだけなので、モデルは各段階でどのフィールドをたどるか推測する必要があります	crossplane_resource_tree が resourceRefs をたどります
実際に問題の原因となっているリソースを特定する	いいえ	crossplane_diagnose が、表面的な症状ではなく、最も深い階層にある障害を見つけます
Crossplane の外部でインフラストラクチャが変更されたことを検知する	いいえ。spec と status は返せますが、両者が一致すべきものだとは認識しません	crossplane_drift_detect が、望ましい状態と観測された状態の差分を検出します
削除が停止している理由を説明する	いいえ	crossplane_deleting_resources が、削除を妨げている Usage、ファイナライザー、プロバイダーを特定します
削除によって最初に何が失われるかを説明する	いいえ	crossplane_impact が、操作前に影響範囲を報告します
クラスターに触れずに変更をシミュレーションする	いいえ	crossplane_composition_render が関数パイプラインをオフラインで実行します
クラスターに書き込む	はい。常に、作成、更新、削除、exec が可能です	明示的に指示した場合のみです。デフォルトでは無効で、削除は一切行わず、Crossplane の種類に限定され、管理対象リソースを手動で書き込むのではなく、プラットフォーム API 経由でプロビジョニングします

この最後の行は、一般的な Kubernetes の作業以上に重要です。Crossplane コントロールプレーンでは、削除されたオブジェクトは ReplicaSet が再作成する Pod ではなく、本番データベースです。このサーバーを本番環境に接続しても、何も変更できません。--read-only=false を指定して開発用コントロールプレーンに接続しても、リソースを削除できず、Secret、Deployment、RBAC ルールにも一切触れることはできません。

このサーバーに組み込まれている Crossplane の知識は、次のとおりです。

• Crossplane のカテゴリ（managed、composite、claim）に基づいてリソースを検出するため、個々のプロバイダーについて教えなくても、すべてのプロバイダーで動作します。
• リソースの Ready／Synced とパッケージの Installed／Healthy を読み取り、その違いをモデルに説明します。
• resourceRefs をたどってコンポジションツリーを構築します。これは crossplane beta trace と同じビューです。
• 一時停止中のリソースや Observe 専用リソースのドリフトは修正されないことを把握しているため、警告すべき状況と、何も起こらない状況を区別します。
• 名前空間付きコンポジットリソースや spec.crossplane の参照先など、Crossplane v1 と v2 の両方の構成に対応しています。

クイックスタート

go install github.com/ravibagri5/crossplane-mcp-server/cmd/crossplane-mcp-server@latest

# See what this build exposes
crossplane-mcp-server tools

# Check it can reach your control plane
crossplane-mcp-server call crossplane_status

次に、MCP クライアントに追加し（クライアントの設定を参照）、コントロールプレーンについて質問してください。

インストール

要件

• ソースからインストールする場合、または go install を使う場合は、Go 1.26 以降が必要です。ビルド済みバイナリとコンテナーイメージには、この要件はありません。
• Crossplane がインストールされた Kubernetes クラスターへのアクセス。Crossplane v1 または v2 のどのバージョンでも動作します。
• 任意：crossplane_composition_render でのみ使用する crossplane CLI とコンテナーランタイム。レンダリングではコンポジション関数パイプラインを実行しますが、これは Kubernetes API 経由では実行できません。それ以外のツールは API アクセス以外に必要なものはなく、crossplane_composition_validate を使えば、コンテナーランタイムなしで同様の検証をほとんど行えます。

Go でのインストール

go install github.com/ravibagri5/crossplane-mcp-server/cmd/crossplane-mcp-server@latest

コンテナーイメージ

docker run --rm -i \
  -v "${HOME}/.kube:/home/nonroot/.kube:ro" \
  ghcr.io/ravibagri5/crossplane-mcp-server:latest

バイナリ

Linux、macOS、Windows 用のビルド済みバイナリが、各リリースに添付されています。最近の Go ツールチェーンをお持ちでない場合は、こちらが最も簡単な方法です。

ソースからのインストール

git clone https://github.com/ravibagri5/crossplane-mcp-server.git
cd crossplane-mcp-server
make build
./bin/crossplane-mcp-server tools

レジストリ

このサーバーは以下に掲載されています。

• 公式 MCP レジストリ では io.github.ravibagri5/crossplane-mcp-server として掲載されており、MCP クライアントはここで検索します。
• Smithery でも掲載されており、 クライアントへのワンクリックインストールも利用できます。
• Go パッケージのドキュメントは pkg.go.dev で確認できます。

クライアントの設定

Claude Desktop、Claude Code、Cursor、Windsurf

{
  "mcpServers": {
    "crossplane": {
      "command": "crossplane-mcp-server",
      "args": ["--clusters", "staging,production", "--context", "staging"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "HOME": "/Users/you"
      }
    }
  }
}

kubeconfig のコンテキストが kubelogin や aws などの exec プラグインを介して認証する場合は、PATH と HOME が重要です。 デスクトップアプリケーションは環境変数がほとんど設定されていない状態でサーバーを起動するため、これらがないとプラグインが見つからないか、トークンキャッシュを読み取れません。

Goose

~/.config/goose/config.yaml に記述します。

extensions:
  crossplane:
    enabled: true
    type: stdio
    cmd: /path/to/crossplane-mcp-server
    args: ["--clusters", "staging,production", "--context", "staging"]
    envs:
      PATH: /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin
      HOME: /Users/you
    timeout: 300

Goose に検査だけでなくプロビジョニングも許可するには、args に --read-only=false を追加します。 examples/demo では、使い捨てのクラスターでその一連の流れを確認できます。

VS Code

ワークスペースの .vscode/mcp.json に追加します。

{
  "servers": {
    "crossplane": {
      "type": "stdio",
      "command": "crossplane-mcp-server",
      "args": ["--clusters", "staging,production"]
    }
  }
}

コンテナベースのクライアント

{
  "mcpServers": {
    "crossplane": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.kube:/home/nonroot/.kube:ro",
        "ghcr.io/ravibagri5/crossplane-mcp-server:latest"
      ]
    }
  }
}

ツール

crossplane-mcp-server tools を実行すると、ビルドからこの一覧を出力できます。

resources

管理対象リソース、複合リソース、クレーム。

ツール	回答する内容
crossplane_managed_resources_summary	種類ごとの管理対象リソースの数と、Ready および Synced の数
crossplane_managed_resources_list	存在する管理対象リソース。失敗しているものだけに絞り込むこともできます
crossplane_composite_resources_list	存在する複合リソース（XR）と、それぞれが選択した Composition
crossplane_claims_list	存在するクレームと、それぞれが紐付けられている複合リソース
crossplane_resource_get	1 つのリソースに関するすべての情報：条件、外部名、イベント、マニフェスト
crossplane_resource_tree	クレームまたは複合リソース配下の Composition ツリーと、リソースごとのステータス
crossplane_resource_events	1 つのリソースに対して Crossplane が記録したイベント
crossplane_diagnose	リソースが Ready でない理由と、実際に問題のあるリソース
crossplane_drift_detect	宣言された仕様と一致しなくなったインフラストラクチャと、その差異が修正されるかどうか

packages

ツール	回答する内容
crossplane_providers_list	インストール済みで正常なプロバイダー
crossplane_functions_list	インストール済みで正常な Composition 関数
crossplane_configurations_list	インストール済みで正常な構成
crossplane_package_get	1 つのパッケージとそのリビジョン。イメージの取得エラーや依存関係のエラーも確認できます

compositions

ツール	回答する内容
crossplane_xrds_list	コントロールプレーンが提供するプラットフォーム API
crossplane_xrd_schema	プラットフォーム API が受け取るフィールドと、すぐに編集できるマニフェストの例
crossplane_compositions_list	存在する Composition と、それぞれが実行するパイプライン
crossplane_composition_get	1 つの Composition の完全な定義
crossplane_composition_validate	実行せずに Composition が動作しない理由を確認できます
crossplane_composition_render	ドライランとして、Composition が実際に作成するものを確認できます

config

コントロールプレーン自体の設定です。

ツール	回答する内容
crossplane_environment_configs_list	存在する EnvironmentConfig と、保持しているデータ
crossplane_deployment_runtime_configs_list	存在するランタイム設定と、それらを使用するパッケージ
crossplane_managed_resource_definitions_list	アクティブな管理対象リソースの種類（Crossplane v2）
crossplane_managed_resource_activation_policies_list	それらの定義を有効化するポリシー

diagnostics

ツール	回答する内容
crossplane_clusters_list	このサーバーが接続できるコントロールプレーン
crossplane_status	1 回の呼び出しで確認できるコントロールプレーン全体の健全性
crossplane_unhealthy_resources	現在失敗しているすべてのリソースと、その理由
crossplane_deleting_resources	削除が滞っているリソースと、処理を妨げているもの
crossplane_usages_list	削除から保護されているものと、それを必要としているもの
crossplane_impact	削除によって破棄されるものと、削除が阻止されるかどうか
crossplane_api_resources	正確な種類とグループを確認するための Crossplane API の全体像

provisioning

サーバーを --read-only=false で実行しない限り、利用できません。読み取り専用モードと書き込みモードを参照してください。

ツール	内容
crossplane_database_create	コントロールプレーン独自のデータベース API にデータベースを要求し、XRD で宣言されているフィールドを設定します
crossplane_workload_create	ワークロード、アプリ、またはサービスについて同様に処理します
crossplane_resource_apply	自分で作成した XRD、Composition、仕様に Crossplane マニフェストを適用します

--toolsets で一部のツールセットを公開します。

crossplane-mcp-server --toolsets diagnostics,packages

読み取り専用モードと書き込みモード

サーバーは読み取り専用モードで起動します。このモードでは書き込みツールは登録されないため、tools/list に表示されず、呼び出しても「その名前のツールはない」と返されます。つまり、モデルを説得して実行させることはできません。

# Read-only. The default, and what to use against production.
crossplane-mcp-server

# Writes enabled, for a development control plane.
crossplane-mcp-server --read-only=false

書き込みを有効にしても、次の点は変わりません。

• 削除は一切行いません。 書き込みでできるのは作成と更新だけで、それがすべてです。削除ツールはなく、コードベースのどこにも Delete の呼び出しはありません。そのため、アシスタントが誤解した場合の最悪の結果は、不要なリソースが作られることであり、必要なリソースが消されることではありません。crossplane_impact では引き続き、削除によって何が破棄されるかを確認でき、実際の削除は自分で行います。
• 書き込み可能なのは Crossplane の種類だけです。 書き込み処理ではリソースが Crossplane のカテゴリと API グループに照らして確認され、それ以外は拒否されます。そのため、何を要求されても、このサーバーが Secret を作成したり、Deployment を編集したり、自身に RBAC 権限を付与したりすることはありません。
• プロビジョニングはプラットフォーム API を通じて行われます。 crossplane_database_create は XRD を読み取り、宣言されているフィールドを設定します。管理対象リソースを独自に作り出したり、API に認識されていないフィールドを設定したりすることはありません。設定先のない値は破棄せず、結果として報告します。
• すべてサーバーサイド適用で行われます。 フィールドマネージャー crossplane-mcp-server を使用するため、再試行しても重複せずに更新され、kubectl apply も並行して引き続き使用できます。すべてのオブジェクトにはラベル app.kubernetes.io/created-by=crossplane-mcp-server が付与されます。
• すべての書き込みツールで dryRun を利用できます。 API サーバーにマニフェストを検証させ、永続化は行いません。
• 引き続き RBAC によって権限が決まります。 --read-only=false を指定しても、認証情報にない権限を付与することはできません。deploy/rbac-write.yaml は、プラットフォーム API に対する作成と更新のみを許可するための出発点です。それ以外は一切許可せず、delete も許可しません。

プロンプト

ツールはモデルに「何ができるか」を伝えます。プロンプトは、経験豊富なオペレーターならどのような順序で作業するかを伝えます。これにより、会話のたびに、クレームの診断は最も深刻に見える管理対象リソースではなく、クレームから始めるという手順を再確認する必要がなくなります。

多くのクライアントでは、スラッシュコマンドやプロンプト選択画面として表示されます。

プロンプト	内容
diagnose_resource	失敗しているリソースをプロバイダーのエラーまでたどり、修正方法を提案します
control_plane_review	対応が必要な順に並べた健全性レポートを作成します
explain_platform_api	プラットフォーム API が提供する機能と、その利用方法を説明します
assess_deletion	削除を実行する前に、その影響範囲を確認します

ツールを直接呼び出す

call は MCP クライアントを介さずに 1 つのツールを実行し、返された内容を表示します。サーバーからクラスターに接続できることを確認したり、モデルが返したと説明する内容ではなく、ツールが実際に何を返すかを確かめたりするために使用します。

# No arguments
crossplane-mcp-server call crossplane_status

# Arguments are the same JSON an MCP client would send
crossplane-mcp-server call crossplane_managed_resources_list '{"status":"not-ready"}'
crossplane-mcp-server call crossplane_diagnose '{"kind":"Bucket","name":"app-data"}'

# The structured payload the model receives, instead of the text rendering
crossplane-mcp-server call crossplane_status --json

# Against another control plane
crossplane-mcp-server call crossplane_status --context prod

# Write tools need the mode as well, and dryRun shows what would be submitted
crossplane-mcp-server --read-only=false call crossplane_database_create \
  '{"name":"orders-db","size":"small","dryRun":true}'

crossplane-mcp-server tools --json を実行すると、ツールが受け付ける正確な引数を確認できます。

設定

フラグ	デフォルト	説明
--kubeconfig	$KUBECONFIG、次に ~/.kube/config、次にクラスター内	kubeconfig ファイルへのパス
--context	現在のコンテキスト	ツールでクラスターが指定されていない場合に使用する kubeconfig のコンテキスト
--clusters	すべてのコンテキスト	ターゲットとして公開するコンテキストのコンマ区切りリスト
--namespace	コンテキストの名前空間、なければ default	名前空間付きリソースのデフォルトの名前空間
--toolsets	すべて	公開するツールセットのコンマ区切りリスト
--read-only	true	コントロールプレーンを変更するすべてのツールを非表示にします。--read-only=false にすると作成と更新が有効になります。どちらのモードでも削除はできません
--http-address	(未設定)	stdio の代わりに、このアドレスでストリーミング可能な HTTP を提供します
--log-level	info	debug、info、warn、error。ログは常に stderr に出力されます
--tool-timeout	2m	1 回のツール呼び出しに許可される最大時間。0 にすると無効になります
--version		バージョンを表示して終了します

複数のコントロールプレーン

1 つのサーバーから複数のコントロールプレーンに接続できます。すべてのツールは、そのいずれかを指定する省略可能な cluster 引数を受け取ります。また、crossplane_clusters_list によって、モデルは利用可能なクラスターを確認できます。

crossplane-mcp-server --clusters staging,production --context staging

アシスタントに 「本番環境で何か問題が起きていますか？」 と尋ねると、cluster: "production" が渡されます。クラスターを省略すると、--context が使用されます。

--clusters を使用してください。 これを指定しないと、kubeconfig 内のすべてのコンテキストがターゲットになります。数百のコンテキストがあるマシンでは、サンドボックスを使うつもりがアシスタントから本番クラスターにアクセスできてしまう可能性があります。作業に使用する少数のコンテキストを指定すると、処理が速くなるだけでなく、安全性も高まります。

クライアントは必要になったときに作成され、キャッシュされるため、到達できないクラスターがあっても他のクラスターの動作は妨げられず、クラスター一覧の取得にもコストはかかりません。

認証情報

ソース	仕組み
kubeconfig のコンテキスト	exec プラグイン経由で認証するコンテキストも含め、そのまま使用されます
クラウド ID（AKS、EKS、GKE）	kubeconfig にすでに定義されている kubelogin や aws などの exec プラグインを通じて動作します
サービスアカウント	kubeconfig がない場合に自動的に使用されます。クラスター内デプロイではこの状態になります

exec プラグインは通常の実行可能ファイルです。そのため、デスクトップアプリから起動したサーバーでは、プラグインを見つけられるよう PATH に含め、独自のトークンキャッシュを見つけられるよう HOME を設定する必要があります。ほとんどの MCP クライアントは、環境変数がほとんど設定されていない状態でサーバーを起動します。ターミナルではクラスターに接続できるのに、クライアントでは接続できない場合、通常はこれが原因です。

{
  "command": "crossplane-mcp-server",
  "args": ["--clusters", "staging,production"],
  "env": {
    "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
    "HOME": "/Users/you"
  }
}

クラスター内で実行する

サーバーを検査対象のコントロールプレーン内で実行する場合は、ストリーミング可能な HTTP トランスポートを提供します。

crossplane-mcp-server --http-address :8080

MCP エンドポイントは /mcp で、稼働状態確認用のエンドポイントは /healthz です。kubeconfig がない場合、サーバーはポッドのサービスアカウントを使用します。マニフェストは deploy/ にあります。

HTTP トランスポートには、認証機能が組み込まれていません。認証プロキシの背後に配置するか、プライベートネットワーク内にとどめてください。SECURITY.md を参照してください。

必要な RBAC

サーバーは読み取りのみを行います。すべてのツールに対応するクラスターロールは次のとおりです。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: crossplane-mcp-server
rules:
  # Discovery, so the server can find managed and composite resource kinds.
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions"]
    verbs: ["get", "list"]
  # Everything Crossplane owns.
  - apiGroups: ["*.crossplane.io"]
    resources: ["*"]
    verbs: ["get", "list"]
  # Managed resources, which live in provider-specific API groups.
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["get", "list"]
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list"]

クラスター全体への読み取り権限を付与したくない場合は、deploy/rbac-minimal.yaml を使用すると、権限を限定できます。ただし、一部のツールから警告が返されます。

--read-only=false を指定して起動したサーバーには書き込み動詞も必要です。アシスタントに使用させるプラットフォーム API に対してのみ付与してください。deploy/rbac-write.yaml は、指定された API グループのリストに対して create、update、patch を付与します。削除するツールはないため delete は付与せず、パッケージも対象外です。Provider のインストールでは、他者のコードがクラスター内で実行されるためです。

コントリビューション

コントリビューションを歓迎します。まずはCONTRIBUTING.mdをご確認ください。開発ワークフロー、ツールの追加方法、サインオフ要件について説明しています。初めての方に適した課題には good first issueのラベルが付いています。

プルリクエストを作成する前に、次の2点をご確認ください。

• プルリクエストの送信先は、長期的に維持される唯一のブランチであるmainです。リリースはmain上の署名付きタグです。docs/branching.mdをご覧ください。
• 質問やまとまっていないアイデアは、課題トラッカーではなくディスカッションに投稿してください。方向性が合意された後、メンテナーが課題を作成します。

書き込みサポート、監査、スキャンなど、プロジェクトの今後の計画についてはROADMAP.mdをご覧ください。

このプロジェクトはCrossplane 行動規範に従い、GOVERNANCE.mdに記載された方針のもとで運営されています。

セキュリティ

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

ライセンス

Apache License 2.0です。LICENSEをご覧ください。

crossplane-mcp-serverはコミュニティプロジェクトであり、CrossplaneまたはCNCFの公式プロジェクトではありません。CrossplaneはThe Linux Foundationの登録商標です。