The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Crossplane listing page.
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.
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:
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.
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:
managed, composite,
claim), so it works with every provider without being taught about any of
them.Ready/Synced on resources and Installed/Healthy on packages,
and explains the difference to the model.resourceRefs to build the composition tree, the same view as
crossplane beta trace.Observe-only resource is never corrected,
which is the difference between a warning and a non-event.spec.crossplane reference location.Then add it to your MCP client (see Client configuration) and ask it about your control plane.
go install. The
pre-built binaries and the container image have no such requirement.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.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.
This server is listed in:
io.github.ravibagri5/crossplane-mcp-server, which is where MCP clients
look it up.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.
In ~/.config/goose/config.yaml:
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.
Add to .vscode/mcp.json in your workspace:
Run crossplane-mcp-server tools to print this list from your build.
resourcesManaged 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 |
configHow 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 |
provisioningWithheld 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:
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.
What stays true even with writes enabled:
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.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.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.--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.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 |
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.
Run crossplane-mcp-server tools --json to see the exact arguments a tool
accepts.
| 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 |
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.
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.
| 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:
Serve the streamable HTTP transport when the server runs inside the control plane it inspects:
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.
The server only ever reads. A cluster role that covers every tool:
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.
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:
develop, never main. main only receives release/*
and hotfix/* branches, so that every change ships through a release
candidate first. See docs/branching.md.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.
Please report vulnerabilities privately. See SECURITY.md.
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.