Crossplane

crossplane-mcp-server

一个 Model Context Protocol 服务，可让 AI 助手了解 Crossplane 控制平面。

向助手询问 “我有多少个受管资源？有没有资源出现故障？”，它会根据你的实际控制平面给出答案，并说明每个故障的原因，而不是凭空猜测。

> 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 资源，而通用的 resources_list 只要指定 apiVersion 和 kind，就能返回你的 XRD。访问从来都不是问题。

问题在于，它不知道这些内容意味着什么，而且还会轻易将其删除。

	通用 Kubernetes MCP	本服务
访问 Crossplane CRD	是	是
从 claim 追踪到它创建的基础设施	不行。它只会返回对象；模型必须猜测每一步该跟踪哪个字段	crossplane_resource_tree 会为你遍历 resourceRefs
指出实际出问题的资源	不行	crossplane_diagnose 会找出最深层的故障，而不是顶层的症状
发现 Crossplane 之外发生的基础设施变更	不行。它可以返回 spec 和 status，但不知道两者本应一致	crossplane_drift_detect 会对比期望状态与观测状态
解释删除为何卡住	不行	crossplane_deleting_resources 会指出阻止删除的 Usage、finalizer 或 provider
说明删除操作会先摧毁什么	不行	crossplane_impact 会在你执行操作前报告影响范围
在不触碰集群的情况下模拟变更	不行	crossplane_composition_render 会离线运行函数流水线
写入你的集群	可以，始终可以：创建、更新、删除、exec	只有你明确要求时才会写入。默认关闭，绝不删除，仅限 Crossplane 类型，并通过你的平台 API 进行置备，而不是手动写入受管资源

对于 Crossplane 控制平面而言，最后一行比普通 Kubernetes 工作更重要。被删除的 Crossplane 对象不是 ReplicaSet 会重新创建的 pod，而是生产数据库。将本服务指向生产环境时，它无法修改任何内容；将其指向开发控制平面并设置 --read-only=false，它仍然无法删除资源，也完全无法触碰 Secret、Deployment 或 RBAC 规则。

本服务内置的 Crossplane 知识包括：

• 按 Crossplane 类别（managed、composite、claim）发现资源，因此无需针对任何 provider 进行专门配置，就能适用于所有 provider。
• 读取资源的 Ready/Synced 状态和软件包的 Installed/Healthy 状态，并向模型解释其中的区别。
• 遍历 resourceRefs 来构建组合树，与 crossplane beta trace 的视图相同。
• 知道已暂停资源或仅 Observe 的资源，其漂移永远不会得到纠正；这正是警告与无需处理的情况之间的区别。
• 同时支持 Crossplane v1 和 v2 的布局，包括命名空间级组合资源和 spec.crossplane 引用位置。

快速开始

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 1.26 或更高版本，适用于从源代码安装或使用 go install 安装的情况。预构建二进制文件和容器映像没有此要求。
• 能够访问已安装 Crossplane 的 Kubernetes 集群。Crossplane v1 或 v2 的任意版本均可。
• 可选：crossplane CLI 和容器运行时，仅供 crossplane_composition_render 使用。渲染需要执行组合函数流水线，这无法通过 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，也提供一键安装到客户端的功能。
• pkg.go.dev 提供 Go 包文档。

客户端配置

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

将 --read-only=false 添加到 args，即可让 Goose 进行资源配置，而不仅仅是检查。 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	单个资源的所有信息：条件、外部名称、事件、清单
crossplane_resource_tree	声明或组合资源下的组合树，以及每个资源的状态
crossplane_resource_events	Crossplane 针对单个资源记录的事件
crossplane_diagnose	资源未处于 Ready 状态的原因，以及实际出错的资源
crossplane_drift_detect	哪些基础设施与声明的规格不再匹配，以及是否会进行修正

packages

工具	能解答的问题
crossplane_providers_list	安装了哪些 Provider，以及它们是否健康
crossplane_functions_list	安装了哪些组合函数，以及它们是否健康
crossplane_configurations_list	安装了哪些配置，以及它们是否健康
crossplane_package_get	单个包及其修订版本；镜像拉取和依赖错误会显示在其中

compositions

工具	能解答的问题
crossplane_xrds_list	此控制平面提供哪些平台 API
crossplane_xrd_schema	平台 API 接受哪些字段，并附带可直接编辑的示例清单
crossplane_compositions_list	有哪些 Composition，以及它们运行什么流水线
crossplane_composition_get	单个 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 上，哪些受管资源类型处于 Active 状态
crossplane_managed_resource_activation_policies_list	哪些策略会激活这些定义

diagnostics

工具	能回答的问题
crossplane_clusters_list	此服务可以访问哪些控制平面
crossplane_status	一次调用即可查看控制平面的整体健康状况
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	应用 Crossplane 清单，适用于你自行编写的 XRD、Composition 和规格

使用 --toolsets 暴露部分工具集：

crossplane-mcp-server --toolsets diagnostics,packages

只读和写入模式

服务以只读模式启动。在此模式下，写入工具不会注册，因此 tools/list 不会列出这些工具，调用时也会返回“no tool named”：模型无从说服服务执行写入。

# 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 客户端。可用它检查服务器是否能连接到你的集群，并查看工具实际返回的内容，而不是模型声称返回的内容。

# 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	（未设置）	在此地址提供可流式传输的 HTTP，而不是使用 stdio
--log-level	info	debug、info、warn 或 error。日志始终写入 stderr
--tool-timeout	2m	单次工具调用可运行的最长时间。0 表示禁用
--version		输出版本并退出

多个控制平面

一个服务器可以连接多个控制平面。每个工具都接受可选的 cluster 参数，用于指定其中一个控制平面；crossplane_clusters_list 会告知模型有哪些可用的控制平面。

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

向助手提问 “生产环境中是否有任何故障？”，它就会传入 cluster: "production"；省略集群时则会使用 --context。

使用 --clusters。 如果不使用它，kubeconfig 中的每个上下文都会成为目标。在有数百个上下文的机器上，这意味着助手可能会连接到生产集群，而你本想连接的是沙盒。只指定你经常使用的少数几个上下文，既更快也更安全。

客户端会按需创建并缓存，因此某个集群无法访问不会影响其他集群；列出集群也不会产生任何开销。

凭据

来源	工作方式
Kubeconfig 上下文	按原样使用，包括通过 exec 插件进行身份验证的上下文
云身份（AKS、EKS、GKE）	通过 kubeconfig 中已声明的 exec 插件工作，例如 kubelogin 或 aws
服务账号	没有 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 时，服务器会使用 Pod 的服务账号。清单位于 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，因为没有工具会执行删除；同时也不包含 packages，因为安装 Provider 会在你的集群中运行他人的代码。

贡献

非常欢迎贡献。请先阅读 CONTRIBUTING.md，其中介绍了开发工作流、如何添加工具以及签署要求。适合新手的议题已标记为 good first issue。

提交拉取请求前，请注意以下两点：

• 拉取请求的目标分支为 main，它是唯一的长期维护分支。版本发布使用 main 上经过签名的标签。请参阅 docs/branching.md。
• 问题和尚未成形的想法应发布在 Discussions， 而不是议题跟踪器。达成共识后，维护者会创建议题。

项目未来的发展方向，包括写入支持、审计和扫描，详见 ROADMAP.md。

本项目遵循 Crossplane 行为准则，并按 GOVERNANCE.md 中的说明进行治理。

安全

请私下报告漏洞。请参阅 SECURITY.md。

许可证

Apache License 2.0。请参阅 LICENSE。

crossplane-mcp-server 是一个社区项目，并非 Crossplane 或 CNCF 官方项目。Crossplane 是 The Linux Foundation 的注册商标。