Portainer MCP

Gerencie recursos do Portainer e execute comandos Docker ou Kubernetes por meio de um assistente de IA.

GitHub
238

Documentação

Portainer MCP

Servidor MCP para Portainer, gerado a partir da especificação OpenAPI do Portainer via FastMCP.

[!IMPORTANT] Portainer MCP não é mais a forma suportada de usar um LLM com Portainer. Isso é o Portainer Command, disponível para clientes do Portainer Business Edition (incluindo a licença gratuita de 3 nós).

Este servidor permanece disponível como está para pessoas que desejam continuar usando-o, mas é fornecido sem suporte, garantia ou SLA, e não é recomendado para ambientes de produção. Este repositório pode ser arquivado no futuro.

Visão geral

Este servidor MCP expõe a API REST do Portainer como ferramentas MCP: listar e inspecionar ambientes, gerenciar fluxos de trabalho GitOps, solucionar problemas de recursos Docker e Kubernetes. Ele também suporta o proxy de solicitações para as APIs subjacentes de Docker e K8s de cada ambiente.

Combine a versão secundária do servidor MCP com a versão secundária da sua instância do Portainer — por exemplo, servidor MCP 2.45.x com Portainer 2.45.x. Consulte Compatibilidade de versões para detalhes.

Uso pretendido

O Portainer MCP é destinado a avaliação, homelabs e outros usos não relacionados à produção. Ele não é suportado em ambientes empresariais, de produção ou qualquer outro onde tempo de atividade, postura de segurança ou integridade de dados importem. Não há SLA, nenhuma resposta garantida a problemas, nenhum desenvolvimento adicional de recursos e nenhum compromisso de roadmap. Se você o executar, estará escolhendo o autosuporte.

Para uma forma suportada de usar um LLM com Portainer, use o Portainer Command (Business Edition, incluindo a licença gratuita de 3 nós).

Primeiros passos

O servidor MCP suporta diferentes cenários de implantação:

  • executá-lo localmente via uvx
  • instalá-lo como um pacote MCP
  • implantá-lo como um contêiner

Use a abordagem uvx ou o pacote MCP para explorar os recursos do MCP localmente e implantá-lo dentro da sua infraestrutura como um contêiner para uma configuração de implantação baseada em equipe.

[!NOTE] Antes de usar o MCP, certifique-se de gerar uma chave de API no Portainer em Minha conta → Tokens de acesso primeiro, pois ambos os caminhos precisam dela.

Pacote MCP (instalação com um clique)

Uma maneira conveniente de testar o servidor MCP localmente. Seu cliente deve suportar pacotes MCP:

  1. Baixe o pacote .mcpb autônomo para sua plataforma na última versão
  2. Clique duas vezes para instalar
  3. Insira sua URL do Portainer e a chave de API.

Usuário único (stdio via uvx)

A outra maneira de testar o servidor MCP localmente. Executa como um processo stdio na sua máquina e conecta-se diretamente à instância do Portainer.

[!NOTE] O uv deve estar instalado e disponível no PATH. Consulte a documentação de instalação do uv.

Defina PORTAINER_TLS_VERIFY=0 se sua instância do Portainer usar certificados TLS autoassinados.

Registre com o Claude Code:

claude mcp add portainer \
  -e PORTAINER_URL=https://portainer.example.com \
  -e PORTAINER_API_KEY=ptr_xxxxxxxxxxxxxxxx \
  -- uvx --from "mcp-portainer~=2.45.0" mcp-portainer

Para outros clientes, consulte docs/distribution/.

Implantação em equipe (contêiner)

Uma maneira de ter vários usuários interagindo com sua instância do Portainer via MCP. Implantado como um container dentro da sua infraestrutura, acessado pelos usuários de suas estações de trabalho via HTTPS. Um segredo compartilhado protege o servidor MCP e cada cliente também encaminha sua própria chave de API do Portainer para que cada usuário atue sob sua própria identidade do Portainer.

[!IMPORTANT] Tanto o segredo de proteção quanto a chave de API do Portainer de cada usuário são enviados pela rede. A implantação em contêiner exige que você declare uma postura de transporte: traga seus próprios certificados TLS, ateste uma configuração de proxy reverso com terminação TLS ou opte explicitamente por texto simples.

Texto simples é uma escolha deliberada e perigosa — veja as três opções abaixo.

NÃO é recomendado expor este servidor MCP na internet pública; hospede-o dentro da sua infraestrutura privada, mesmo atrás de um proxy TLS.

Veja mais informações abaixo sobre os diferentes cenários de implantação. Para qualquer um desses cenários:

  • Defina PORTAINER_MCP_ALLOWED_HOSTS para o nome de host ou endereço IP que os usuários usarão para acessar o MCP — caso contrário, a lista de permissões de rebinding de DNS rejeita a solicitação com 421.
  • PORTAINER_MCP_AUTH_TOKEN é obrigatório no modo HTTP. É o segredo compartilhado de proteção frontal que você distribui aos seus usuários; o cliente MCP deles o envia via cabeçalho Authorization. Ele apenas admite a solicitação — o que cada usuário pode fazer é governado pela própria chave de API do Portainer. A única exceção: atrás de um proxy ciente de identidade que possui o cabeçalho Authorization, use PORTAINER_MCP_TRUST_PROXY_AUTH=1 em vez disso (veja a Opção D).

Opção A - Certificados BYO

[!NOTE] O servidor avisará se usar certificados autoassinados. Usar um certificado de CA privado não avisará, mas em ambos os casos você provavelmente precisará passar por alguns obstáculos para configurar os clientes MCP para aceitá-lo.

Implante o contêiner para usar seu próprio conjunto de certificados TLS:

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp -p 17717:17717 \
	-v /etc/portainer-mcp/tls:/tls:ro \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
	-e PORTAINER_MCP_TLS_CERT=/tls/cert.pem \
	-e PORTAINER_MCP_TLS_KEY=/tls/key.pem \
	portainer/portainer-mcp:2.45

Em seguida, conecte seu cliente:

claude mcp add portainer --transport http https://mcp.example.com:17717/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

Opção B - Proxy reverso com terminação TLS

[!NOTE] Não publique a porta do contêiner ao usar um proxy reverso na frente do contêiner MCP; apenas o proxy deve conseguir alcançá-lo.

Use o IP exato do seu proxy, se estável, para PORTAINER_MCP_FORWARDED_ALLOW_IPS.

Certifique-se de que seu proxy encaminhe os cabeçalhos originais Host e X-Forwarded-Proto: https.

Traga seu próprio proxy e configure um proxy com terminação TLS na frente do contêiner:

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
	-e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
	portainer/portainer-mcp:2.45

Em seguida, conecte seu cliente:

claude mcp add portainer --transport http https://mcp.example.com/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

Opção C - HTTP em texto simples

[!WARNING] NÃO é recomendado usar isso fora de uma implantação de rede privada confiável.

Use o sinalizador PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 para iniciar o servidor apenas com HTTP.

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp -p 17717:17717 \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
	-e PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 \
	portainer/portainer-mcp:2.45

Em seguida, conecte seu cliente:

claude mcp add portainer --transport http http://mcp.example.com:17717/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

Opção D - Proxy ciente de identidade (MCP OAuth)

Se seus usuários autenticarem por meio de um proxy ciente de identidade que fala o fluxo MCP OAuth (como Pomerium no modo de servidor MCP), o proxy emite seu próprio token de acesso e possui o cabeçalho Authorization. Declare a postura de autenticação trust-proxy em vez de PORTAINER_MCP_AUTH_TOKEN:

[!NOTE] Mesmas regras da Opção B: não publique a porta do contêiner (apenas o proxy pode alcançá-lo) e certifique-se de que o proxy encaminhe os cabeçalhos originais Host e X-Forwarded-Proto: https.

Cada solicitação ainda precisa da própria chave de API do Portainer do chamador em X-Portainer-API-Key — faça o proxy injetá-la por usuário ou faça cada cliente enviá-la. O proxy lida com quem entra; a chave do Portainer governa o que eles podem fazer.

docker run -d --name portainer-mcp \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_AUTH=1 \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
	-e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
	portainer/portainer-mcp:2.45

Nenhum token de proteção está configurado: a solicitação é admitida por atestação do proxy (deve chegar de PORTAINER_MCP_FORWARDED_ALLOW_IPS — herdado como limite de confiança, * recusa iniciar) e pela chave validada do Portainer do chamador. Se o servidor MCP encerrar o TLS por conta própria em vez do proxy, defina PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr> no lugar das duas linhas TRUST_PROXY_TLS/FORWARDED_ALLOW_IPS. Consulte docs/configuration.md para as regras completas de postura.

Restringindo e expandindo os recursos do servidor MCP

O servidor MCP vem com os seguintes recursos habilitados por padrão:

  • Suporte básico de operação do Portainer (configurações, versão, ambientes...)
  • Suporte de operação do Docker
  • Suporte de operação do Kubernetes
  • Suporte de proxy Docker e Kubernetes
  • Redação de valores de variáveis de ambiente (habilitado por padrão)

Para restringir ou expandir esse conjunto de recursos, consulte docs/profiles.md.

Compatibilidade de versões

Combine a versão secundária do servidor MCP com a versão secundária do seu Portainer. A versão principal+secundária acompanha a versão da API do Portainer que a especificação incorporada visa.

Versão do servidorPortainer (CE / EE)
2.45.x2.45.x
2.44.x2.44.x
2.43.x2.43.x
2.42.x2.42.x
2.41.x2.41.x

Para mais informações sobre a política de versionamento, consulte docs/versioning.md.

Configuração

O servidor MCP expõe diferentes recursos, como:

  • Habilitar diferentes conjuntos de ferramentas com base na configuração de perfil específica
  • Ampliar a cobertura da API especificando tags extras a serem cobertas
  • Expor apenas recursos somente leitura
  • Desabilitar recursos de proxy
  • Ajustar os recursos de transporte e configurar a postura TLS
  • Configuração de registro

Para mais informações sobre a configuração do servidor MCP, consulte docs/configuration.md.

Obtendo ajuda

O Portainer MCP não tem canal oficial de suporte. Problemas podem ser relatados no GitHub, mas fazer isso não cria nenhuma obrigação para o projeto de responder, triar ou corrigi-los.

Não há versão suportada do Portainer MCP; ele é fornecido como está e sem garantia.