crossplane-mcp-server

A Model Context Protocol server that lets AI assistants understand a Crossplane control plane.

Ask your assistant "how many managed resources do I have and is anything broken?" and it will answer from your actual control plane, with the reason for every failure, instead of guessing.

text

> 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.

The server is read-only by default: the tools that create and update are not registered at all unless you start it with --read-only=false, so a client cannot see them, let alone call them. Nothing deletes in either mode. Turn writes on and the same assistant can provision from your platform APIs:

text

> 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.

Nothing there names a Kubernetes kind. The tool found the platform API this control plane offers, read the schema its XRD declares and filled it in. See examples/demo for a control plane you can try it on without a cloud account.

Why not a generic Kubernetes MCP server?
Quick start
Installation
Client configuration
Tools
Read-only and write modes
Prompts
Calling a tool directly
Configuration
Multiple control planes
Running in a cluster
Required RBAC
Contributing
Security
License

Why not a generic Kubernetes MCP server?

A general purpose Kubernetes MCP server can already reach every object on a Crossplane control plane: Crossplane resources are Kubernetes resources, and a generic resources_list with an apiVersion and a kind will happily return your XRDs. Access was never the problem.

The problem is that it does not know what any of it means, and it will happily delete it.

	Generic Kubernetes MCP	This server
Reach Crossplane CRDs	Yes	Yes
Follow a claim to the infrastructure it created	No. It returns objects; the model has to guess which field to follow at each hop	`crossplane_resource_tree` walks `resourceRefs` for you
Say which resource is actually at fault	No	`crossplane_diagnose` finds the deepest failure, not the symptom at the top
Notice infrastructure changed outside Crossplane	No. It can return `spec` and `status` but has no idea they are meant to match	`crossplane_drift_detect` diffs desired against observed
Explain why a delete is hanging	No	`crossplane_deleting_resources` names the Usage, finalizer or provider holding it
Say what a delete would destroy first	No	`crossplane_impact` reports the blast radius before you act
Simulate a change without touching the cluster	No	`crossplane_composition_render` runs the function pipeline offline
Write to your cluster	Yes, always: create, update, delete, exec	Only if you ask. Off by default, never deletes, limited to Crossplane kinds, and it provisions through your platform APIs rather than writing managed resources by hand

That last row matters more here than it does for ordinary Kubernetes work. On a Crossplane control plane a deleted object is not a pod that a ReplicaSet will recreate, it is a production database. Point this server at production and it cannot mutate anything; point it at a development control plane with --read-only=false and it still cannot delete a resource, and cannot touch a Secret, a Deployment or an RBAC rule at all.

Underneath, the Crossplane knowledge this server encodes is:

It discovers resources by Crossplane category (managed, composite, claim), so it works with every provider without being taught about any of them.
It reads Ready/Synced on resources and Installed/Healthy on packages, and explains the difference to the model.
It walks resourceRefs to build the composition tree, the same view as crossplane beta trace.
It knows that drift on a paused or Observe-only resource is never corrected, which is the difference between a warning and a non-event.
It supports both Crossplane v1 and v2 layouts, including namespaced composite resources and the spec.crossplane reference location.

Quick start

shell

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

Then add it to your MCP client (see Client configuration) and ask it about your control plane.

Installation

Requirements

Go 1.26 or newer, if you install from source or with go install. The pre-built binaries and the container image have no such requirement.
Access to a Kubernetes cluster with Crossplane installed. Any version of Crossplane v1 or v2 works.
Optional: the crossplane CLI and a container runtime, used only by crossplane_composition_render. Rendering executes the composition function pipeline, which cannot be done through the Kubernetes API. Every other tool needs nothing beyond API access, and crossplane_composition_validate covers most of the same ground without a container runtime.

Go install

shell

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

Container image

Terminal

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

Binaries

Pre-built binaries for Linux, macOS and Windows are attached to every release. These are the easiest option if you do not have a recent Go toolchain.

From source

shell

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

Registries

This server is listed in:

Official MCP Registry as io.github.ravibagri5/crossplane-mcp-server, which is where MCP clients look it up.
Smithery, which also offers one-click installation into a client.
pkg.go.dev for the Go package documentation.

Client configuration

Claude Desktop, Claude Code, Cursor, Windsurf

config.json

{
  "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"
      }
    }
  }
}

PATH and HOME matter whenever a kubeconfig context authenticates through an exec plugin such as kubelogin or aws. Desktop applications launch servers with a near-empty environment, so without them the plugin is either not found or cannot read its token cache.

Goose

In ~/.config/goose/config.yaml:

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

Add --read-only=false to args to let goose provision as well as inspect. examples/demo walks through that end to end on a throwaway cluster.

VS Code

Add to .vscode/mcp.json in your workspace:

config.json

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

Container based clients

config.json

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

Tools

Run crossplane-mcp-server tools to print this list from your build.

`resources`

Managed resources, composite resources and claims.

Tool	What it answers
`crossplane_managed_resources_summary`	How many managed resources exist, by kind, and how many are Ready and Synced
`crossplane_managed_resources_list`	Which managed resources exist, optionally only the failing ones
`crossplane_composite_resources_list`	Which composite resources (XRs) exist and which Composition each selected
`crossplane_claims_list`	Which claims exist and which composite each is bound to
`crossplane_resource_get`	Everything about one resource: conditions, external name, events, manifest
`crossplane_resource_tree`	The composition tree below a claim or composite, with per-resource status
`crossplane_resource_events`	The events Crossplane recorded against one resource
`crossplane_diagnose`	Why a resource is not Ready, and which resource is actually at fault
`crossplane_drift_detect`	Which infrastructure no longer matches its declared spec, and whether that will be corrected

`packages`

Tool	What it answers
`crossplane_providers_list`	Which providers are installed and healthy
`crossplane_functions_list`	Which composition functions are installed and healthy
`crossplane_configurations_list`	Which configurations are installed and healthy
`crossplane_package_get`	One package plus its revisions, where image pull and dependency errors appear

`compositions`

Tool	What it answers
`crossplane_xrds_list`	Which platform APIs this control plane offers
`crossplane_xrd_schema`	The fields a platform API takes, with a ready-to-edit example manifest
`crossplane_compositions_list`	Which Compositions exist and what pipeline they run
`crossplane_composition_get`	The full definition of one Composition
`crossplane_composition_validate`	Why a Composition does not work, without running anything
`crossplane_composition_render`	What a Composition would actually create, as a dry run

`config`

How the control plane itself is configured.

Tool	What it answers
`crossplane_environment_configs_list`	Which EnvironmentConfigs exist and what data they hold
`crossplane_deployment_runtime_configs_list`	Which runtime configs exist and which packages use them
`crossplane_managed_resource_definitions_list`	Which managed resource kinds are Active, on Crossplane v2
`crossplane_managed_resource_activation_policies_list`	Which policies activate those definitions

`diagnostics`

Tool	What it answers
`crossplane_clusters_list`	Which control planes this server can reach
`crossplane_status`	The overall health of the control plane in one call
`crossplane_unhealthy_resources`	Everything that is currently failing, and why
`crossplane_deleting_resources`	What is stuck deleting, and what is holding it up
`crossplane_usages_list`	What is protected from deletion, and what needs it
`crossplane_impact`	What a deletion would destroy, and whether it would be blocked
`crossplane_api_resources`	The Crossplane API surface, to find exact kinds and groups

`provisioning`

Withheld unless the server runs with --read-only=false. See Read-only and write modes.

Tool	What it does
`crossplane_database_create`	Asks the control plane's own database API for a database, filling in the fields its XRD declares
`crossplane_workload_create`	The same for a workload, app or service
`crossplane_resource_apply`	Applies a Crossplane manifest, for XRDs, Compositions and specs you built yourself

Expose a subset with --toolsets:

shell

crossplane-mcp-server --toolsets diagnostics,packages

Read-only and write modes

The server starts read-only. In that mode the write tools are never registered, so tools/list does not mention them and a call to one comes back as "no tool named": there is nothing for a model to be talked into.

shell

# 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

What stays true even with writes enabled:

Nothing deletes. Writes create and update, and that is the whole list. There is no delete tool and no Delete call anywhere in the codebase, so the worst outcome of a confused assistant is a resource you did not want, not one you did. crossplane_impact still tells you what a deletion would destroy, and you run the deletion yourself.
Only Crossplane kinds can be written. The write path checks the resource against Crossplane's categories and API groups and refuses everything else, so the server cannot create a Secret, edit a Deployment or grant itself RBAC no matter what it is asked.
Provisioning goes through your platform APIs. crossplane_database_create reads the XRD and sets the fields it declares; it does not invent a managed resource and it does not set fields the API has never heard of. Values with nowhere to go are reported back rather than dropped.
Everything is a server-side apply, under the field manager crossplane-mcp-server, so a retry updates rather than duplicates and kubectl apply keeps working alongside it. Every object gets the label app.kubernetes.io/created-by=crossplane-mcp-server.
dryRun is available on every write tool, which asks the API server to validate the manifest without persisting it.
RBAC still decides. --read-only=false cannot grant permissions the credentials do not have. deploy/rbac-write.yaml is a starting point that allows create and update on your platform APIs and nothing else — not even delete.

Prompts

Tools tell a model what it can do. Prompts tell it the order an experienced operator would do things in, so it does not have to rediscover on every conversation that diagnosing a claim starts at the claim and not at the managed resource that looks angriest.

Most clients surface these as slash commands or a prompt picker.

Prompt	What it does
`diagnose_resource`	Walks a failing resource down to the provider error and proposes the fix
`control_plane_review`	Produces a health report ordered by what needs attention first
`explain_platform_api`	Explains what a platform API offers and how to ask for one
`assess_deletion`	Works out the blast radius of a deletion before anyone runs it

Calling a tool directly

call runs one tool and prints what it returns, without an MCP client in the way. Use it to check the server can reach your cluster, and to see what a tool really returns rather than what a model says it returned.

shell

# 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}'

Run crossplane-mcp-server tools --json to see the exact arguments a tool accepts.

Configuration

Flag	Default	Description
`--kubeconfig`	`$KUBECONFIG`, then `~/.kube/config`, then in-cluster	Path to a kubeconfig file
`--context`	current context	Kubeconfig context used when a tool does not name a cluster
`--clusters`	every context	Comma separated contexts to expose as targets
`--namespace`	context namespace, else `default`	Default namespace for namespaced resources
`--toolsets`	all	Comma separated toolsets to expose
`--read-only`	`true`	Withhold every tool that changes the control plane. `--read-only=false` enables create and update; nothing deletes in either mode
`--http-address`	(unset)	Serve streamable HTTP on this address instead of stdio
`--log-level`	`info`	`debug`, `info`, `warn` or `error`. Logs always go to stderr
`--tool-timeout`	`2m`	Maximum time a single tool call may run. `0` disables
`--version`		Print the version and exit

Multiple control planes

One server can talk to several control planes. Every tool takes an optional cluster argument naming one of them, and crossplane_clusters_list tells a model which are available.

shell

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

Ask your assistant "is anything failing in production?" and it passes cluster: "production"; omit the cluster and it uses --context.

Use --clusters. Without it every context in your kubeconfig becomes a target, which on a machine with a few hundred contexts means an assistant could reach a production cluster when you meant a sandbox. Naming the handful you work with is both faster and safer.

Clients are created lazily and cached, so an unreachable cluster does not stop the others from working, and listing clusters costs nothing.

Credentials

Source	How it works
Kubeconfig context	Used as-is, including contexts that authenticate through an exec plugin
Cloud identity (AKS, EKS, GKE)	Works through the exec plugin the kubeconfig already declares, such as `kubelogin` or `aws`
Service account	Used automatically when there is no kubeconfig, which is the case for the in-cluster deployment

Exec plugins are ordinary executables, so a server launched by a desktop application needs PATH to include them, and HOME so they can find their own token cache. Most MCP clients start servers with a near-empty environment, which is the usual reason a cluster works in a terminal but not in the client:

config.json

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

Running in a cluster

Serve the streamable HTTP transport when the server runs inside the control plane it inspects:

shell

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

The MCP endpoint is /mcp and a liveness endpoint is served at /healthz. The server uses the pod's service account when no kubeconfig is present. Manifests are in deploy/.

The HTTP transport has no built-in authentication. Put it behind an authenticating proxy, or keep it on a private network. See SECURITY.md.

Required RBAC

The server only ever reads. A cluster role that covers every tool:

yaml

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"]

If you would rather not grant a cluster-wide read, deploy/rbac-minimal.yaml narrows the permissions at the cost of some tools returning warnings.

A server started with --read-only=false needs write verbs as well, and should only be given them on the platform APIs an assistant is meant to use. deploy/rbac-write.yaml grants create, update and patch on a named list of API groups. It grants no delete, because no tool deletes, and leaves out packages: installing a Provider runs somebody else's code in your cluster.

Contributing

Contributions are very welcome. Start with CONTRIBUTING.md, which covers the development workflow, how to add a tool, and the sign-off requirement. Good first issues are labelled good first issue.

Two things to know before you open a pull request:

Pull requests target develop, never main. main only receives release/* and hotfix/* branches, so that every change ships through a release candidate first. See docs/branching.md.
Questions and half-formed ideas belong in Discussions, not the issue tracker. A maintainer will open the issue once the shape is agreed.

Where the project is going, including write support, auditing and scanning, is in ROADMAP.md.

This project follows the Crossplane Code of Conduct and is governed as described in GOVERNANCE.md.

Security

Please report vulnerabilities privately. See SECURITY.md.

License

Apache License 2.0. See LICENSE.

crossplane-mcp-server is a community project and is not an official Crossplane or CNCF project. Crossplane is a registered trademark of The Linux Foundation.

Crossplane README

crossplane-mcp-server

Contents

Why not a generic Kubernetes MCP server?

Quick start

Installation

Requirements

Go install

Container image

Binaries

From source

Registries

Client configuration

Claude Desktop, Claude Code, Cursor, Windsurf

Goose

VS Code

Container based clients

Tools

`resources`

`packages`

`compositions`

`config`

`diagnostics`

`provisioning`

Read-only and write modes

Prompts

Calling a tool directly

Configuration

Multiple control planes

Credentials

Running in a cluster

Required RBAC

Contributing

Security

License