Portainer MCP Docker

Servidor MCP Portainer Dockerizado (stdio/HTTP transmissível) para implantação fácil junto ao Portainer

Documentação

portainer-mcp-docker

Versão Dockerizada do Portainer MCP Server para fácil implantação.

Em vez de baixar e gerenciar binários manualmente, este projeto fornece imagens Docker mínimas baseadas em Alpine que podem ser implantadas junto com o Portainer usando Docker Compose.

Recursos

Imagem mínima do Alpine Linux com o binário oficial portainer-mcp
Duas variantes: stdio (local) e HTTP (remoto/web)
Suporte a múltiplas arquiteturas (linux/amd64, linux/arm64)
Atualizações automáticas via GitHub Actions quando novas versões upstream são publicadas
Atualizações da imagem base via Dependabot com auto-merge (correções de segurança, atualizações do Alpine)
Tags versionadas correspondentes à versão upstream (ex.: v0.7.0-1)

Variantes de Imagem

Tag da Imagem	Transporte	Caso de Uso
`latest` / `v0.7.0-1`	stdio	Clientes MCP locais (Claude Desktop, Claude Code CLI)
`http` / `v0.7.0-1-http`	Streamable HTTP	Acesso remoto (Claude Web, servidores compartilhados)

stdio (padrão)

A imagem padrão. Os clientes MCP iniciam o contêiner e se comunicam via stdin/stdout. Melhor para configurações locais onde o cliente MCP roda na mesma máquina.

HTTP

Encapsula o servidor MCP com mcp-proxy para expô-lo via Streamable HTTP. Suporta autenticação por token bearer para que o endpoint não seja acessível publicamente. Melhor para acesso remoto, por exemplo, conectar do Claude Web a uma instância do Portainer no seu servidor.

Instalação

Pré-requisitos

Uma instância Portainer em execução
Um token de acesso à API do Portainer (gerado na interface do Portainer em Minha Conta > Tokens de Acesso)
Docker e Docker Compose

Variante stdio (Local)

Início Rápido

docker pull ghcr.io/serraniel/portainer-mcp-docker:latest

docker run -i --rm ghcr.io/serraniel/portainer-mcp-docker:latest \
  -server your-portainer:9443 \
  -token your-api-token

Rede: Portainer no Mesmo Host

Quando o Portainer roda na mesma máquina que o contêiner MCP, localhost dentro do contêiner refere-se ao próprio contêiner, não ao host. Use host.docker.internal em vez disso:

docker run -i --rm \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/serraniel/portainer-mcp-docker:latest \
  -server host.docker.internal:9443 \
  -token your-api-token

Configuração do Cliente MCP

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "portainer": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "ghcr.io/serraniel/portainer-mcp-docker:latest",
        "-server", "host.docker.internal:9443",
        "-token", "your-api-token"
      ]
    }
  }
}

Substitua host.docker.internal:9443 pelo hostname:port real do seu Portainer se ele rodar em uma máquina diferente.

Claude Code

Adicione às configurações MCP do seu Claude Code:

{
  "mcpServers": {
    "portainer": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "ghcr.io/serraniel/portainer-mcp-docker:latest",
        "-server", "host.docker.internal:9443",
        "-token", "your-api-token"
      ]
    }
  }
}

Variante HTTP (Remoto)

Gerando Tokens

A variante HTTP requer dois tokens:

Token da API do Portainer (PORTAINER_TOKEN) — autentica o servidor MCP na sua instância do Portainer. Gere um na interface do Portainer em Minha Conta > Tokens de Acesso > Adicionar token de acesso.
Token bearer MCP (API_ACCESS_TOKEN) — protege o endpoint HTTP para que apenas clientes MCP autorizados possam se conectar. Este é um segredo que você mesmo cria. Gere um token aleatório seguro:

openssl rand -hex 32

Use a saída como seu MCP_API_TOKEN no arquivo .env e configure o mesmo valor no cabeçalho Authorization: Bearer <token> do seu cliente MCP.

Início Rápido

docker pull ghcr.io/serraniel/portainer-mcp-docker:http

docker run -d --rm \
  -p 8080:8080 \
  -e PORTAINER_SERVER=your-portainer:9443 \
  -e PORTAINER_TOKEN=your-portainer-api-token \
  -e API_ACCESS_TOKEN=your-mcp-bearer-token \
  ghcr.io/serraniel/portainer-mcp-docker:http

Docker Compose

services:
  portainer:
    image: portainer/portainer-ce:latest
    restart: always
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

  portainer-mcp:
    image: ghcr.io/serraniel/portainer-mcp-docker:http
    restart: always
    ports:
      - "8080:8080"
    environment:
      - PORTAINER_SERVER=portainer:9443
      - PORTAINER_TOKEN=${PORTAINER_TOKEN}
      - API_ACCESS_TOKEN=${MCP_API_TOKEN}
      # Optional:
      # - PORTAINER_READ_ONLY=true
      # - PORTAINER_DISABLE_VERSION_CHECK=true
      # - MCP_PORT=8080
      # - MCP_HOST=0.0.0.0

volumes:
  portainer_data:

Crie um arquivo .env:

PORTAINER_TOKEN=your-portainer-api-token
MCP_API_TOKEN=your-mcp-bearer-token

Configuração do Cliente MCP (Remoto)

Claude Web / Claude Desktop (URL Remota)

Configure seu cliente MCP para conectar ao endpoint HTTP:

URL: http://your-server:8080/sse
Autorização: Token bearer (o MCP_API_TOKEN que você configurou)

Claude Code (Remoto)

{
  "mcpServers": {
    "portainer": {
      "type": "url",
      "url": "http://your-server:8080/sse",
      "headers": {
        "Authorization": "Bearer your-mcp-bearer-token"
      }
    }
  }
}

Variáveis de Ambiente (HTTP)

Variável	Obrigatório	Descrição
`PORTAINER_SERVER`	Sim	Endereço do servidor Portainer como `host:port` (sem prefixo de protocolo, HTTPS é usado automaticamente)
`PORTAINER_TOKEN`	Sim	Token de acesso à API do Portainer
`API_ACCESS_TOKEN`	Recomendado	Token bearer para autenticação do endpoint MCP
`PORTAINER_READ_ONLY`	Não	Defina como `true` para modo somente leitura
`PORTAINER_DISABLE_VERSION_CHECK`	Não	Defina como `true` para pular a validação de versão
`MCP_PORT`	Não	Porta de escuta HTTP (padrão: `8080`)
`MCP_HOST`	Não	Endereço de escuta HTTP (padrão: `0.0.0.0`)

Opções de Linha de Comando (stdio)

Todas as flags do binário upstream são suportadas:

Flag	Descrição
`-server <host:port>`	Endereço do servidor Portainer, sem prefixo de protocolo (obrigatório)
`-token <token>`	Token de acesso à API do Portainer (obrigatório)
`-tools <path>`	Caminho para arquivo YAML de ferramentas personalizadas
`-read-only`	Restringir a operações somente leitura (apenas requisições GET)
`-disable-version-check`	Pular validação de versão do servidor Portainer

Versionamento

As tags de imagem seguem o formato v<upstream>-<build>:

v0.7.0-1 - Primeira compilação do upstream v0.7.0 (stdio)
v0.7.0-1-http - Mesma versão, variante HTTP
v0.7.0-2 - Recompilação (ex.: atualização de segurança da imagem base)
latest - Compilação stdio mais recente
http - Compilação HTTP mais recente

Como Funcionam as Atualizações Automáticas

Gatilho	O que acontece
Nova versão upstream	Verificação diária cria uma nova tag (ex.: `v0.8.0-1`) e compila ambas as imagens
PR do Dependabot mesclado	Auto-mesclado após teste de compilação, incrementa o número da compilação e recompila
Disparo manual	O workflow pode ser acionado manualmente com uma versão upstream específica

Documentação Upstream

Para documentação completa sobre os recursos, ferramentas e compatibilidade de versão do Portainer MCP server, consulte o README upstream.

Licença

Este projeto é licenciado sob a European Union Public License v1.2 (EUPL-1.2).

O binário upstream portainer-mcp é licenciado sob a Zlib License.