crossplane-mcp-server

Um servidor de Model Context Protocol que permite que assistentes de IA entendam um plano de controle Crossplane.

Documentação

crossplane-mcp-server

Um servidor Model Context Protocol que permite que assistentes de IA entendam um plano de controle Crossplane.

Pergunte ao seu assistente "quantos recursos gerenciados eu tenho e há algo quebrado?" e ele responderá com base no seu plano de controle real, com o motivo de cada falha, em vez de adivinhar.

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

Toda ferramenta é somente leitura. Este servidor não pode criar, atualizar ou excluir nada no seu plano de controle.

Conteúdo

Por que não um servidor MCP Kubernetes genérico?
Início rápido
Instalação
Configuração do cliente
Ferramentas
Prompts
Chamando uma ferramenta diretamente
Configuração
Múltiplos planos de controle
Executando em um cluster
RBAC necessário
Contribuindo
Segurança
Licença

Por que não um servidor MCP Kubernetes genérico?

Um servidor MCP Kubernetes de propósito geral já pode acessar todos os objetos em um plano de controle Crossplane: os recursos Crossplane são recursos Kubernetes, e um resources_list genérico com um apiVersion e um kind retornará seus XRDs sem problemas. O acesso nunca foi o problema.

O problema é que ele não sabe o que tudo isso significa, e ele excluirá alegremente qualquer coisa.

	Kubernetes MCP genérico	Este servidor
Acessar CRDs do Crossplane	Sim	Sim
Seguir uma claim até a infraestrutura que ela criou	Não. Ele retorna objetos; o modelo precisa adivinhar qual campo seguir em cada etapa	`crossplane_resource_tree` percorre `resourceRefs` para você
Dizer qual recurso é realmente o culpado	Não	`crossplane_diagnose` encontra a falha mais profunda, não o sintoma no topo
Notar que a infraestrutura mudou fora do Crossplane	Não. Ele pode retornar `spec` e `status`, mas não tem ideia de que eles devem corresponder	`crossplane_drift_detect` compara o desejado com o observado
Explicar por que uma exclusão está travada	Não	`crossplane_deleting_resources` identifica o Usage, finalizer ou provider que a está segurando
Dizer o que uma exclusão destruiria primeiro	Não	`crossplane_impact` relata o raio de impacto antes de você agir
Simular uma alteração sem tocar no cluster	Não	`crossplane_composition_render` executa o pipeline de funções offline
Escrever no seu cluster	Sim: criar, atualizar, excluir, exec	Nunca. Não existe caminho de código que mute qualquer coisa

Essa última linha importa mais aqui do que no trabalho Kubernetes comum. Em um plano de controle Crossplane, um objeto excluído não é um pod que um ReplicaSet recriará; é um banco de dados de produção. Uma superfície de ferramentas que não pode mutar é algo que você pode apontar para o seu plano de controle de produção sem uma revisão de alterações.

Por baixo, o conhecimento Crossplane que este servidor codifica é:

Ele descobre recursos pela categoria Crossplane (managed, composite, claim), então funciona com todos os providers sem precisar ser ensinado sobre nenhum deles.
Ele lê Ready/Synced em recursos e Installed/Healthy em pacotes, e explica a diferença para o modelo.
Ele percorre resourceRefs para construir a árvore de composição, a mesma visão do crossplane beta trace.
Ele sabe que drift em um recurso pausado ou somente Observe nunca é corrigido, o que é a diferença entre um aviso e um não-evento.
Ele suporta os layouts Crossplane v1 e v2, incluindo recursos compostos com namespace e o local de referência spec.crossplane.

Início rápido

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

Depois, adicione-o ao seu cliente MCP (veja Configuração do cliente) e pergunte sobre o seu plano de controle.

Instalação

Requisitos

Go 1.26 ou mais recente, se você instalar a partir do código-fonte ou com go install. Os binários pré-compilados e a imagem de contêiner não têm esse requisito.
Acesso a um cluster Kubernetes com Crossplane instalado. Qualquer versão do Crossplane v1 ou v2 funciona.
Opcional: o CLI do crossplane e um runtime de contêiner, usados apenas pelo crossplane_composition_render. A renderização executa o pipeline de funções de composição, o que não pode ser feito pela API Kubernetes. Toda outra ferramenta precisa apenas de acesso à API, e o crossplane_composition_validate cobre grande parte do mesmo terreno sem um runtime de contêiner.

Instalação com Go

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

Imagem de contêiner

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

Binários

Binários pré-compilados para Linux, macOS e Windows estão anexados a cada release. Eles são a opção mais fácil se você não tiver um toolchain Go recente.

A partir do código-fonte

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

Registros

Este servidor está listado em:

Registro MCP Oficial como io.github.ravibagri5/crossplane-mcp-server, que é onde os clientes MCP o procuram.
Smithery, que também oferece instalação com um clique em um cliente.
pkg.go.dev para a documentação do pacote Go.

Configuração do cliente

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 e HOME importam sempre que um contexto de kubeconfig autentica por meio de um plugin exec, como kubelogin ou aws. Aplicativos de desktop iniciam servidores com um ambiente quase vazio, então sem eles o plugin não é encontrado ou não consegue ler seu cache de tokens.

Goose

No ~/.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

VS Code

Adicione ao .vscode/mcp.json no seu workspace:

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

Clientes baseados em contêiner

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

Ferramentas

Execute crossplane-mcp-server tools para imprimir esta lista a partir do seu build.

`resources`

Recursos gerenciados, recursos compostos e claims.

Ferramenta	O que ela responde
`crossplane_managed_resources_summary`	Quantos recursos gerenciados existem, por tipo, e quantos estão Ready e Synced
`crossplane_managed_resources_list`	Quais recursos gerenciados existem, opcionalmente apenas os com falha
`crossplane_composite_resources_list`	Quais recursos compostos (XRs) existem e qual Composition cada um selecionou
`crossplane_claims_list`	Quais claims existem e a qual composto cada uma está vinculada
`crossplane_resource_get`	Tudo sobre um recurso: condições, nome externo, eventos, manifesto
`crossplane_resource_tree`	A árvore de composição abaixo de uma claim ou composto, com status por recurso
`crossplane_resource_events`	Os eventos que o Crossplane registrou contra um recurso
`crossplane_diagnose`	Por que um recurso não está Ready e qual recurso é realmente o culpado
`crossplane_drift_detect`	Qual infraestrutura não corresponde mais ao seu spec declarado e se isso será corrigido

`packages`

Ferramenta	O que ela responde
`crossplane_providers_list`	Quais providers estão instalados e saudáveis
`crossplane_functions_list`	Quais funções de composição estão instaladas e saudáveis
`crossplane_configurations_list`	Quais configurations estão instaladas e saudáveis
`crossplane_package_get`	Um pacote mais suas revisões, onde erros de pull de imagem e dependências aparecem

`compositions`

Ferramenta	O que ela responde
`crossplane_xrds_list`	Quais APIs de plataforma este plano de controle oferece
`crossplane_xrd_schema`	Os campos que uma API de plataforma aceita, com um manifesto de exemplo pronto para editar
`crossplane_compositions_list`	Quais Compositions existem e qual pipeline elas executam
`crossplane_composition_get`	A definição completa de uma Composition
`crossplane_composition_validate`	Por que uma Composition não funciona, sem executar nada
`crossplane_composition_render`	O que uma Composition realmente criaria, como um dry run

`config`

Como o próprio plano de controle está configurado.

Ferramenta	O que ela responde
`crossplane_environment_configs_list`	Quais EnvironmentConfigs existem e quais dados eles contêm
`crossplane_deployment_runtime_configs_list`	Quais configs de runtime existem e quais pacotes os usam
`crossplane_managed_resource_definitions_list`	Quais tipos de recursos gerenciados estão Active, no Crossplane v2
`crossplane_managed_resource_activation_policies_list`	Quais políticas ativam essas definições

`diagnostics`

Ferramenta	O que ela responde
`crossplane_clusters_list`	Quais planos de controle este servidor pode alcançar
`crossplane_status`	A saúde geral do plano de controle em uma única chamada
`crossplane_unhealthy_resources`	Tudo que está falhando atualmente e por quê
`crossplane_deleting_resources`	O que está travado na exclusão e o que o está segurando
`crossplane_usages_list`	O que está protegido contra exclusão e o que precisa disso
`crossplane_impact`	O que uma exclusão destruiria e se ela seria bloqueada
`crossplane_api_resources`	A superfície da API Crossplane, para encontrar tipos e grupos exatos

Exponha um subconjunto com --toolsets:

crossplane-mcp-server --toolsets diagnostics,packages

Prompts

Ferramentas dizem a um modelo o que ele pode fazer. Prompts dizem a ele a ordem em que um operador experiente faria as coisas, para que ele não precise redescobrir a cada conversa que diagnosticar uma claim começa na claim e não no recurso gerenciado que parece mais irritado.

A maioria dos clientes exibe esses como comandos de barra ou um seletor de prompts.

Prompt	O que ele faz
`diagnose_resource`	Percorre um recurso com falha até o erro do provider e propõe a correção
`control_plane_review`	Produz um relatório de saúde ordenado pelo que precisa de atenção primeiro
`explain_platform_api`	Explica o que uma API de plataforma oferece e como solicitar uma
`assess_deletion`	Calcula o raio de impacto de uma exclusão antes que alguém a execute

Chamando uma ferramenta diretamente

call executa uma ferramenta e imprime o que ela retorna, sem um cliente MCP no caminho. Use-o para verificar se o servidor consegue alcançar seu cluster e para ver o que uma ferramenta realmente retorna, em vez do que um modelo diz que ela retornou.

# 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

Execute crossplane-mcp-server tools --json para ver os argumentos exatos que uma ferramenta aceita.

Configuração

Flag	Padrão	Descrição
`--kubeconfig`	`$KUBECONFIG`, depois `~/.kube/config`, depois in-cluster	Caminho para um arquivo kubeconfig
`--context`	contexto atual	Contexto do kubeconfig usado quando uma ferramenta não nomeia um cluster
`--clusters`	todos os contextos	Contextos separados por vírgula para expor como alvos
`--namespace`	namespace do contexto, senão `default`	Namespace padrão para recursos com namespace
`--toolsets`	todos	Conjuntos de ferramentas separados por vírgula para expor
`--http-address`	(não definido)	Servir HTTP streamable neste endereço em vez de stdio
`--log-level`	`info`	`debug`, `info`, `warn` ou `error`. Os logs sempre vão para stderr
`--tool-timeout`	`2m`	Tempo máximo que uma única chamada de ferramenta pode executar. `0` desativa
`--version`		Imprime a versão e sai

Múltiplos planos de controle

Um servidor pode conversar com vários planos de controle. Toda ferramenta aceita um argumento opcional cluster nomeando um deles, e crossplane_clusters_list informa a um modelo quais estão disponíveis.

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

Pergunte ao seu assistente "há algo falhando em produção?" e ele passará cluster: "production"; omita o cluster e ele usará --context.

Use --clusters. Sem ele, todo contexto no seu kubeconfig se torna um alvo, o que em uma máquina com algumas centenas de contextos significa que um assistente poderia alcançar um cluster de produção quando você queria um sandbox. Nomear os poucos com os quais você trabalha é mais rápido e mais seguro.

Os clientes são criados de forma preguiçosa e armazenados em cache, então um cluster inacessível não impede os outros de funcionar, e listar clusters não custa nada.

Credenciais

Fonte	Como funciona
Contexto do kubeconfig	Usado como está, incluindo contextos que autenticam por meio de um plugin exec
Identidade na nuvem (AKS, EKS, GKE)	Funciona por meio do plugin exec que o kubeconfig já declara, como `kubelogin` ou `aws`
Conta de serviço	Usada automaticamente quando não há kubeconfig, que é o caso da implantação no cluster

Plugins exec são executáveis comuns, então um servidor iniciado por um aplicativo de desktop precisa de PATH para incluí-los, e HOME para que eles possam encontrar seu próprio cache de tokens. A maioria dos clientes MCP inicia servidores com um ambiente quase vazio, que é o motivo usual de um cluster funcionar em um terminal, mas não no cliente:

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

Executando em um cluster

Sirva o transporte HTTP streamable quando o servidor for executado dentro do plano de controle que ele inspeciona:

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

O endpoint MCP é /mcp e um endpoint de liveness é servido em /healthz. O servidor usa a conta de serviço do pod quando não há kubeconfig presente. Os manifestos estão em deploy/.

O transporte HTTP não tem autenticação integrada. Coloque-o atrás de um proxy autenticador, ou mantenha-o em uma rede privada. Consulte SECURITY.md.

RBAC necessário

O servidor apenas lê. Uma função de cluster que cobre todas as ferramentas:

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

Se você preferir não conceder uma leitura em todo o cluster, deploy/rbac-minimal.yaml restringe as permissões ao custo de algumas ferramentas retornarem avisos.

Contribuindo

Contribuições são muito bem-vindas. Comece com CONTRIBUTING.md, que cobre o fluxo de trabalho de desenvolvimento, como adicionar uma ferramenta e o requisito de assinatura. Boas primeiras issues são rotuladas good first issue.

Este projeto segue o Código de Conduta do Crossplane e é governado conforme descrito em GOVERNANCE.md.

Segurança

Por favor, relate vulnerabilidades de forma privada. Consulte SECURITY.md.

Licença

Apache License 2.0. Consulte LICENSE.

crossplane-mcp-server é um projeto da comunidade e não é um projeto oficial do Crossplane ou da CNCF. Crossplane é uma marca registrada da The Linux Foundation.