crossplane-mcp-server

README

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.

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

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

Contents

• 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

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

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

Container image

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

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

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

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:

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

Container based clients

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

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.

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

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

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:

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

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:

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.