Portainer MCP

Gestiona recursos de Portainer y ejecuta comandos de Docker o Kubernetes a través de un asistente de IA.

GitHub
238

Documentación

Portainer MCP

Servidor MCP para Portainer, generado a partir de la especificación OpenAPI de Portainer mediante FastMCP.

[!IMPORTANT] Portainer MCP ya no es la forma compatible de usar un LLM con Portainer. Eso es Portainer Command, disponible para clientes de Portainer Business Edition (incluida la licencia gratuita de 3 nodos).

Este servidor sigue disponible tal cual para quienes quieran seguir usándolo, pero se proporciona sin soporte, garantía ni SLA, y no se recomienda para entornos de producción. Este repositorio podría archivarse en el futuro.

Descripción general

Este servidor MCP expone la API REST de Portainer como herramientas MCP: listar e inspeccionar entornos, gestionar flujos de trabajo GitOps, solucionar problemas de recursos Docker y Kubernetes. También admite el proxy de solicitudes a las API subyacentes de Docker y K8s de cada entorno.

Haz coincidir la versión menor del servidor MCP con la menor de tu instancia de Portainer — p. ej., servidor MCP 2.45.x con Portainer 2.45.x. Consulta Compatibilidad de versiones para más detalles.

Uso previsto

Portainer MCP está pensado para evaluación, homelabs y otros usos no productivos. No está soportado en entornos empresariales, de producción ni en cualquier otro donde el tiempo de actividad, la postura de seguridad o la integridad de los datos sean importantes. No hay SLA, ni respuesta garantizada a incidencias, ni desarrollo adicional de funciones, ni compromiso de hoja de ruta. Si lo ejecutas, eliges auto-soportarte.

Para una forma compatible de usar un LLM con Portainer, usa Portainer Command (Business Edition, incluida la licencia gratuita de 3 nodos).

Primeros pasos

El servidor MCP admite diferentes escenarios de despliegue:

  • ejecutarlo localmente mediante uvx
  • instalarlo como un paquete MCP
  • desplegarlo como un contenedor

Usa el enfoque de uvx o el paquete MCP para explorar las capacidades de MCP localmente y desplegarlo dentro de tu infraestructura como contenedor para una configuración de despliegue basada en equipo.

[!NOTE] Antes de usar el MCP, asegúrate de generar una clave de API en Portainer en Mi cuenta → Tokens de acceso primero, ya que ambas rutas la necesitan.

Paquete MCP (instalación en un clic)

Una forma cómoda de probar el servidor MCP localmente. Tu cliente debe admitir paquetes MCP:

  1. Descarga el paquete .mcpb autocontenido para tu plataforma desde la última versión
  2. Haz doble clic para instalar
  3. Introduce tu URL de Portainer y tu clave de API.

Usuario único (stdio mediante uvx)

La otra forma de probar el servidor MCP localmente. Se ejecuta como un proceso stdio en tu máquina y se conecta directamente a la instancia de Portainer.

[!NOTE] uv debe estar instalado y disponible en PATH. Consulta la documentación de instalación de uv.

Establece PORTAINER_TLS_VERIFY=0 si tu instancia de Portainer usa certificados TLS autofirmados.

Regístrate con 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 otros clientes, consulta docs/distribution/.

Despliegue en equipo (contenedor)

Una forma de que varios usuarios interactúen con tu instancia de Portainer mediante MCP. Se despliega como un container dentro de tu infraestructura, al que los usuarios acceden desde sus estaciones de trabajo a través de HTTPS. Un secreto compartido protege el servidor MCP y cada cliente también reenvía su propia clave de API de Portainer para que cada usuario actúe bajo su propia identidad de Portainer.

[!IMPORTANT] Tanto el secreto de puerta como la clave de API de Portainer de cada usuario se envían a través de la red. El despliegue en contenedor requiere que declares una postura de transporte: trae tus propios certificados TLS, certifica una configuración de proxy inverso con terminación TLS u opta explícitamente por texto plano.

El texto plano es una elección deliberada y peligrosa: consulta las tres opciones a continuación.

NO se recomienda exponer este servidor MCP en Internet público; alójalo dentro de tu infraestructura privada, incluso detrás de un proxy TLS.

Consulta más información a continuación sobre los diferentes escenarios de despliegue. Para cualquiera de estos escenarios:

  • Establece PORTAINER_MCP_ALLOWED_HOSTS al nombre de host o dirección IP que los usuarios usarán para llegar al MCP; de lo contrario, la lista de permitidos de rebinding de DNS rechaza la solicitud con 421.
  • PORTAINER_MCP_AUTH_TOKEN es obligatorio en modo HTTP. Es el secreto de puerta frontal compartido que distribuyes a tus usuarios; su cliente MCP lo envía mediante el encabezado Authorization. Solo admite la solicitud — lo que cada usuario puede hacer está gobernado por su propia clave de API de Portainer. La única excepción: detrás de un proxy consciente de identidad que posee el encabezado Authorization, usa PORTAINER_MCP_TRUST_PROXY_AUTH=1 en su lugar (consulta la Opción D).

Opción A - Certificados BYO

[!NOTE] El servidor advertirá si se usan certificados autofirmados. Usar un certificado de CA privada no advertirá, pero en ambos casos probablemente necesitarás saltar algunos obstáculos para configurar los clientes MCP para que lo acepten.

Despliega el contenedor para usar tu propio 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

Luego conecta tu 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>"

Opción B - Proxy inverso con terminación TLS

[!NOTE] No publiques el puerto del contenedor cuando uses un proxy inverso frente al contenedor MCP; solo el proxy debería poder alcanzarlo.

Usa la IP exacta de tu proxy si es estable para PORTAINER_MCP_FORWARDED_ALLOW_IPS.

Asegúrate de que tu proxy reenvíe los encabezados originales Host y X-Forwarded-Proto: https.

Trae tu propio proxy y configura un proxy con terminación TLS frente al contenedor:

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

Luego conecta tu 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>"

Opción C - HTTP en texto plano

[!WARNING] NO se recomienda usar esto fuera de un despliegue de red privada de confianza.

Usa la bandera PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 para iniciar el servidor solo con 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

Luego conecta tu 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>"

Opción D - Proxy consciente de identidad (MCP OAuth)

Si tus usuarios se autentican a través de un proxy consciente de identidad que habla el flujo MCP OAuth (como Pomerium en modo servidor MCP), el proxy acuña su propio token de acceso y posee el encabezado Authorization. Declara la postura de autenticación trust-proxy en lugar de PORTAINER_MCP_AUTH_TOKEN:

[!NOTE] Mismas reglas que la Opción B: no publiques el puerto del contenedor (solo el proxy puede alcanzarlo) y asegúrate de que el proxy reenvíe los encabezados originales Host y X-Forwarded-Proto: https.

Cada solicitud aún necesita la clave de API de Portainer del llamante en X-Portainer-API-Key — haz que el proxy la inyecte por usuario, o que cada cliente la envíe. El proxy gestiona quién entra; la clave de Portainer gobierna qué pueden hacer.

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

No se configura ningún token de puerta: la solicitud se admite por atestación del proxy (debe llegar desde PORTAINER_MCP_FORWARDED_ALLOW_IPS — heredado como límite de confianza, * se niega a arrancar) y por la clave de Portainer validada del llamante. Si el servidor MCP termina TLS por sí mismo en lugar del proxy, establece PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr> en lugar de las dos líneas TRUST_PROXY_TLS/FORWARDED_ALLOW_IPS. Consulta docs/configuration.md para las reglas completas de postura.

Restringir y ampliar las capacidades del servidor MCP

El servidor MCP viene con las siguientes capacidades habilitadas por defecto:

  • Soporte básico de operaciones de Portainer (configuración, versión, entornos...)
  • Soporte de operaciones de Docker
  • Soporte de operaciones de Kubernetes
  • Soporte de proxy de Docker y Kubernetes
  • Redacción de valores de variables de entorno (habilitada por defecto)

Para restringir o ampliar este conjunto de capacidades, consulta docs/profiles.md.

Compatibilidad de versiones

Haz coincidir la versión menor del servidor MCP con la menor de tu Portainer. La mayor+menor sigue la versión de la API de Portainer a la que apunta la especificación integrada.

Versión del 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 más información sobre la política de versionado, consulta docs/versioning.md.

Configuración

El servidor MCP expone diferentes capacidades, como:

  • Habilitar diferentes conjuntos de herramientas según la configuración de perfil específica
  • Ampliar la cobertura de la API especificando etiquetas adicionales a cubrir
  • Exponer solo capacidades de solo lectura
  • Deshabilitar capacidades de proxy
  • Ajustar las capacidades de transporte y configurar la postura TLS
  • Configuración de registro

Para más información sobre la configuración del servidor MCP, consulta docs/configuration.md.

Obtener ayuda

Portainer MCP no tiene canal de soporte oficial. Se pueden reportar incidencias en GitHub, pero hacerlo no crea ninguna obligación para el proyecto de responder, clasificar o corregirlas.

No existe una versión compatible de Portainer MCP; se proporciona tal cual y sin garantía.