Portainer MCP

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

GitHub
217
Prueba este MCPPatrocinado

Documentación

Portainer MCP

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

Descripción general

Este servidor MCP expone la API REST de Portainer como herramientas MCP: listar e inspeccionar entornos, gestionar flujos de trabajo GitOps y 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.44.x con Portainer 2.44.x. Consulta Compatibilidad de versiones para más detalles.

Primeros pasos

El servidor MCP admite diferentes escenarios de despliegue:

  • ejecutarlo localmente mediante uvx
  • instalarlo como un paquete MCP
  • desplegarlo como 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 equipos.

[!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 con un clic)

La forma recomendada de probar el servidor MCP localmente. Tu cliente debe ser compatible con paquetes MCP:

  1. Descarga el paquete .mcpb autónomo para tu plataforma desde la última versión
  2. Haz doble clic para instalarlo
  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 utiliza 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.44.0" mcp-portainer

Para otros clientes, consulta docs/distribution/.

Despliegue en equipo (contenedor)

La forma recomendada 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: aporta 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 reenlace 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 propios (BYO)

[!NOTE] El servidor advertirá si se utilizan certificados autofirmados. Usar un certificado de CA privada no generará advertencias, pero en ambos casos probablemente tendrás que superar 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.44

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

Aporta tu propio proxy y configura un proxy con terminación TLS delante del 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.44

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

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 genera su propio token de acceso y posee el encabezado Authorization. Declara la postura de autenticación de proxy de confianza 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.44

No se configura ningún token de puerta: la solicitud se admite mediante la atestación del proxy (debe llegar desde PORTAINER_MCP_FORWARDED_ALLOW_IPS — heredado como límite de confianza, * se niega a arrancar) y mediante 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 conocer las reglas completas de postura.

Restringir y ampliar las capacidades del servidor MCP

El servidor MCP incluye las siguientes capacidades habilitadas de forma predeterminada:

  • 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 para Docker y Kubernetes
  • Redacción de valores de variables de entorno (habilitada de forma predeterminada)

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