Portainer MCP Docker

Servidor Portainer MCP Dockerizado (stdio/HTTP transmisible) para implementación sencilla junto a Portainer

Documentación

portainer-mcp-docker

Versión dockerizada del Portainer MCP Server para facilitar su despliegue.

En lugar de descargar y gestionar binarios manualmente, este proyecto proporciona imágenes Docker mínimas basadas en Alpine que pueden desplegarse junto a Portainer usando Docker Compose.

Características

Imagen mínima de Alpine Linux con el binario oficial portainer-mcp
Dos variantes: stdio (local) y HTTP (remoto/web)
Soporte multiarquitectura (linux/amd64, linux/arm64)
Actualizaciones automáticas mediante GitHub Actions cuando se publican nuevas versiones upstream
Actualizaciones de la imagen base mediante Dependabot con auto-fusión (parches de seguridad, actualizaciones de Alpine)
Etiquetas versionadas que coinciden con la versión upstream (p. ej., v0.7.0-1)

Variantes de Imagen

Etiqueta de Imagen	Transporte	Caso de Uso
`latest` / `v0.7.0-1`	stdio	Clientes MCP locales (Claude Desktop, Claude Code CLI)
`http` / `v0.7.0-1-http`	HTTP Streamable	Acceso remoto (Claude Web, servidores compartidos)

stdio (predeterminado)

La imagen estándar. Los clientes MCP lanzan el contenedor y se comunican a través de stdin/stdout. Ideal para configuraciones locales donde el cliente MCP se ejecuta en la misma máquina.

HTTP

Envuelve el servidor MCP con mcp-proxy para exponerlo a través de HTTP Streamable. Soporta autenticación con token bearer para que el endpoint no sea accesible públicamente. Ideal para acceso remoto, p. ej., conectarse desde Claude Web a una instancia de Portainer en tu servidor.

Instalación

Requisitos previos

Una instancia de Portainer en ejecución
Un token de acceso a la API de Portainer (generado desde la interfaz de Portainer en Mi Cuenta > Tokens de Acceso)
Docker y Docker Compose

Variante stdio (Local)

Inicio 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

Redes: Portainer en el Mismo Host

Cuando Portainer se ejecuta en la misma máquina que el contenedor MCP, localhost dentro del contenedor se refiere al propio contenedor, no al host. Usa host.docker.internal en su lugar:

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

Configuración del Cliente MCP

Claude Desktop

Añade a tu 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"
      ]
    }
  }
}

Reemplaza host.docker.internal:9443 con la hostname:port real de tu Portainer si se ejecuta en una máquina diferente.

Claude Code

Añade a la configuración MCP de 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)

Generación de Tokens

La variante HTTP requiere dos tokens:

Token de API de Portainer (PORTAINER_TOKEN) — autentica el servidor MCP contra tu instancia de Portainer. Genera uno en la interfaz de Portainer en Mi Cuenta > Tokens de Acceso > Añadir token de acceso.
Token bearer MCP (API_ACCESS_TOKEN) — protege el endpoint HTTP para que solo los clientes MCP autorizados puedan conectarse. Es un secreto que creas tú mismo. Genera un token aleatorio seguro:

openssl rand -hex 32

Usa la salida como tu MCP_API_TOKEN en el archivo .env y configura el mismo valor en el encabezado Authorization: Bearer <token> de tu cliente MCP.

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

Crea un archivo .env:

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

Configuración del Cliente MCP (Remoto)

Claude Web / Claude Desktop (URL Remota)

Configura tu cliente MCP para conectarse al endpoint HTTP:

URL: http://your-server:8080/sse
Autorización: Token bearer (el MCP_API_TOKEN que configuraste)

Claude Code (Remoto)

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

Variables de Entorno (HTTP)

Variable	Requerida	Descripción
`PORTAINER_SERVER`	Sí	Dirección del servidor Portainer como `host:port` (sin prefijo de protocolo, HTTPS se usa automáticamente)
`PORTAINER_TOKEN`	Sí	Token de acceso a la API de Portainer
`API_ACCESS_TOKEN`	Recomendada	Token bearer para autenticación del endpoint MCP
`PORTAINER_READ_ONLY`	No	Establecer a `true` para modo solo lectura
`PORTAINER_DISABLE_VERSION_CHECK`	No	Establecer a `true` para omitir la validación de versión
`MCP_PORT`	No	Puerto de escucha HTTP (predeterminado: `8080`)
`MCP_HOST`	No	Dirección de escucha HTTP (predeterminada: `0.0.0.0`)

Opciones de Línea de Comandos (stdio)

Todos los flags del binario upstream son compatibles:

Flag	Descripción
`-server <host:port>`	Dirección del servidor Portainer, sin prefijo de protocolo (requerido)
`-token <token>`	Token de acceso a la API de Portainer (requerido)
`-tools <path>`	Ruta al archivo YAML de herramientas personalizadas
`-read-only`	Restringir a operaciones de solo lectura (solo solicitudes GET)
`-disable-version-check`	Omitir la validación de versión del servidor Portainer

Versionado

Las etiquetas de imagen siguen el formato v<upstream>-<build>:

v0.7.0-1 - Primera compilación de la versión upstream v0.7.0 (stdio)
v0.7.0-1-http - Misma versión, variante HTTP
v0.7.0-2 - Recompilación (p. ej., actualización de seguridad de la imagen base)
latest - Compilación stdio más reciente
http - Compilación HTTP más reciente

Cómo Funcionan las Actualizaciones Automáticas

Disparador	Qué sucede
Nueva versión upstream	La verificación diaria crea una nueva etiqueta (p. ej., `v0.8.0-1`) y compila ambas imágenes
PR de Dependabot fusionado	Auto-fusión después de la prueba de compilación, incrementa el número de compilación y recompila
Despacho manual	El flujo de trabajo puede activarse manualmente con una versión upstream específica

Documentación Upstream

Para documentación completa sobre las capacidades del servidor MCP de Portainer, herramientas y compatibilidad de versiones de Portainer, consulta el README upstream.

Licencia

Este proyecto está licenciado bajo la Licencia Pública de la Unión Europea v1.2 (EUPL-1.2).

El binario upstream portainer-mcp está licenciado bajo la Licencia Zlib.