Portainer MCP

cobertura

¿Alguna vez deseaste poder preguntarle a Portainer qué está pasando?

¡Ahora puedes! Portainer MCP conecta tu asistente de IA directamente con tus entornos Portainer. Gestiona recursos de Portainer, como usuarios y entornos, o profundiza ejecutando cualquier comando de Docker o Kubernetes directamente a través de la IA.

demostración de portainer-mcp

Descripción general

Portainer MCP es una implementación en desarrollo del Protocolo de Contexto de Modelo (MCP) para entornos Portainer. Este proyecto busca proporcionar una forma estandarizada de conectar las capacidades de gestión de contenedores de Portainer con modelos de IA y otros servicios.

MCP (Protocolo de Contexto de Modelo) es un protocolo abierto que estandariza cómo las aplicaciones proporcionan contexto a los LLM (Grandes Modelos de Lenguaje). De forma similar a cómo USB-C proporciona una forma estandarizada de conectar dispositivos a periféricos, MCP proporciona una forma estandarizada de conectar modelos de IA a diferentes fuentes de datos y herramientas.

Esta implementación se centra en exponer los datos del entorno de Portainer a través del protocolo MCP, lo que permite que los asistentes de IA y otras herramientas interactúen con su infraestructura en contenedores de forma segura y estandarizada.

Consulte las secciones Compatibilidad de versiones de Portainer y Capacidades admitidas para obtener más detalles sobre la compatibilidad y las funciones disponibles.

Nota: Este proyecto está actualmente en desarrollo.

Actualmente está diseñado para funcionar con un token API de administrador de Portainer.

Instalación

Puedes descargar binarios prediseñados para Linux (amd64, arm64) y macOS (arm64) desde la página de Últimas versiones . Encuentra el archivo adecuado para tu sistema operativo y arquitectura en la sección "Recursos".

Descargar el archivo: Normalmente, puedes descargarlo directamente desde la página de lanzamiento. También puedes usar curl . Aquí tienes un ejemplo para macOS (ARM64) versión v0.2.0 :

# Example for macOS (ARM64) - adjust version and architecture as needed
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz

(Los binarios de Linux AMD64 también están disponibles en la página de lanzamiento).

(Opcional, pero recomendado) Verificar la suma de comprobación: Primero, descargue el archivo de suma de comprobación .md5 correspondiente desde la página de lanzamiento. Ejemplo para macOS (ARM64) v0.2.0 :

# Download the checksum file (adjust version/arch)
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5 https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5
# Now verify (output should match the content of the .md5 file)
if [ "$(md5 -q portainer-mcp-v0.2.0-darwin-arm64.tar.gz)" = "$(cat portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5)" ]; then echo "OK"; else echo "FAILED"; fi

(Para Linux, puede usar md5sum -c <checksum_file_name>.md5 ) Si el comando de verificación muestra "OK", el archivo está intacto.

Extraer el archivo:

# Adjust the filename based on the downloaded version/OS/architecture
tar -xzf portainer-mcp-v0.2.0-darwin-arm64.tar.gz

Esto extraerá el ejecutable portainer-mcp .

Mover el ejecutable: mueva el ejecutable a una ubicación en su $PATH (por ejemplo, /usr/local/bin ) o anote su ubicación para el paso de configuración a continuación.

Uso

Con Claude Desktop, configúrelo de la siguiente manera:

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-tools",
                "/tmp/tools.yaml"
            ]
        }
    }
}

Reemplace [IP] , [PORT] y [TOKEN] con la IP, el puerto y el token de acceso API asociado con su instancia de Portainer.

[!NOTA] Por defecto, la herramienta busca "tools.yaml" en el mismo directorio que el binario. Si el archivo no existe, se creará allí con las definiciones de herramienta predeterminadas. Es posible que deba modificar esta ruta como se describió anteriormente, especialmente al usar asistentes de IA como Claude, que tienen permisos de escritura restringidos en el directorio de trabajo.

Personalización de herramientas

De forma predeterminada, las definiciones de herramientas se integran en el binario. La aplicación creará un archivo de herramientas en la ubicación predeterminada si no existe uno.

Puede personalizar las definiciones de herramientas especificando una ruta de archivo de herramientas personalizada utilizando el indicador -tools :

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-tools",
                "/path/to/custom/tools.yaml"
            ]
        }
    }
}

El archivo de herramientas predeterminado está disponible como referencia en internal/tooldef/tools.yaml en el código fuente. Puedes modificar las descripciones de las herramientas y sus parámetros para modificar cómo los modelos de IA las interpretan y deciden usarlas. Incluso puedes eliminar algunas herramientas si no deseas usarlas.

[!ADVERTENCIA] No cambie los nombres de las herramientas ni las definiciones de los parámetros (excepto las descripciones), ya que esto impedirá que las herramientas se registren correctamente y funcionen correctamente.

Modo de solo lectura

Para usuarios preocupados por la seguridad, la aplicación puede ejecutarse en modo de solo lectura. Este modo garantiza que solo se puedan realizar operaciones de lectura, impidiendo por completo cualquier modificación en los recursos de Portainer.

Para habilitar el modo de solo lectura, agregue el indicador -read-only a los argumentos de su comando:

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-read-only"
            ]
        }
    }
}

Al utilizar el modo de solo lectura:

Solo las herramientas de lectura (lista, obtención) estarán disponibles para el modelo de IA
No se cargan todas las herramientas de escritura (crear, actualizar, eliminar)
La herramienta de solicitudes de proxy de Docker no está cargada
La herramienta de solicitudes de proxy de Kubernetes no está cargada

Soporte de versiones de Portainer

Esta herramienta está diseñada para ser compatible con una versión específica de Portainer. La aplicación validará la versión del servidor de Portainer al iniciarse y fallará si no coincide con la versión requerida.

Versión MCP de Portainer	Versión compatible de Portainer
0.1.0	2.28.1
0.2.0	2.28.1
0.3.0	2.28.1
0.4.0	2.29.2
0.4.1	2.29.2
0.5.0	2.30.0

Capacidades admitidas

La siguiente tabla enumera las operaciones admitidas actualmente (última versión) a través de las herramientas MCP:

Recurso	Operación	Descripción	Compatible con la versión
Entornos
	Lista de entornos	Enumere todos los entornos disponibles	0.1.0
	Actualizar etiquetas de entorno	Actualizar las etiquetas asociadas a un entorno	0.1.0
	ActualizarEntornoAccesosDeUsuarios	Actualizar las políticas de acceso de usuarios para un entorno	0.1.0
	ActualizarAccesosDeEquipoDeEntorno	Actualizar las políticas de acceso del equipo para un entorno	0.1.0
Grupos de entorno (grupos de borde)
	Lista de grupos de entornos	Enumere todos los grupos de entornos disponibles	0.1.0
	Crear grupo de entornos	Crear un nuevo grupo de entorno	0.1.0
	ActualizarNombreDeGrupoDeEntorno	Actualizar el nombre de un grupo de entorno	0.1.0
	ActualizarEntornoGrupoEntornos	Actualizar entornos asociados a un grupo	0.1.0
	Actualizar etiquetas de grupo de entorno	Actualizar las etiquetas asociadas a un grupo	0.1.0
Grupos de acceso (grupos de puntos finales)
	Lista de grupos de acceso	Enumere todos los grupos de acceso disponibles	0.1.0
	Crear grupo de acceso	Crear un nuevo grupo de acceso	0.1.0
	ActualizarNombreDeGrupoDeAcceso	Actualizar el nombre de un grupo de acceso	0.1.0
	ActualizarAccesoGrupoAccesoUsuariosAccesos	Actualizar los accesos de usuario para un grupo de acceso	0.1.0
	ActualizarAccesoGrupoEquipoAccesos	Actualizar los accesos del equipo para un grupo de acceso	0.1.0
	Agregar entorno al grupo de acceso	Agregar un entorno a un grupo de acceso	0.1.0
	Eliminar entorno del grupo de acceso	Eliminar un entorno de un grupo de acceso	0.1.0
Pilas (pilas de borde)
	Pilas de listas	Listar todas las pilas disponibles	0.1.0
	Obtener archivo de pila	Obtener el archivo de composición para una pila específica	0.1.0
	Crear pila	Crear una nueva pila de Docker	0.1.0
	UpdateStack	Actualizar una pila Docker existente	0.1.0
Etiquetas
	Lista de etiquetas de entorno	Enumere todas las etiquetas de entorno disponibles	0.1.0
	Crear etiqueta de entorno	Crear una nueva etiqueta de entorno	0.1.0
Equipos
	Lista de equipos	Listar todos los equipos disponibles	0.1.0
	Crear equipo	Crear un nuevo equipo	0.1.0
	ActualizarNombreDelEquipo	Actualizar el nombre de un equipo	0.1.0
	Actualizar miembros del equipo	Actualizar los miembros de un equipo	0.1.0
Usuarios
	Lista de usuarios	Listar todos los usuarios disponibles	0.1.0
	Actualizar usuario	Actualizar un usuario existente	0.1.0
	Obtener configuraciones	Obtener la configuración de la instancia de Portainer	0.1.0
Estibador
	Proxy de Docker	Proxy de CUALQUIER solicitud de API de Docker	0.2.0
Kubernetes
	Proxy de Kubernetes	Proxy de CUALQUIER solicitud de API de Kubernetes	0.3.0

Desarrollo

Estadísticas de código

El repositorio incluye un script auxiliar cloc.sh para calcular líneas de código y otras métricas de los archivos fuente de Go mediante la herramienta cloc . Es posible que deba instalar cloc primero (p. ej., sudo apt install cloc o brew install cloc ).

Ejecute el script desde la raíz del repositorio para ver la salida de resumen predeterminada:

./cloc.sh

Consulte el encabezado de comentarios dentro del script cloc.sh para obtener detalles sobre los indicadores disponibles para recuperar métricas específicas.

Conteo de fichas

Para obtener una estimación de cuántos tokens consumen sus definiciones de herramientas actuales en las indicaciones, puede usar el programa Go y el script de shell proporcionados para consultar el punto final de conteo de tokens de la API de Anthropic.

1. Generar el JSON de herramientas:

Primero, usa el programa token-count de Go para convertir las definiciones de tu herramienta YAML al formato JSON requerido por la API de Anthropic. Ejecútalo desde la raíz del repositorio:

# Replace internal/tooldef/tools.yaml with your YAML file if different
# Replace .tmp/tools.json with your desired output path
go run ./cmd/token-count -input internal/tooldef/tools.yaml -output .tmp/tools.json

Este comando lee las definiciones de herramientas del archivo YAML de entrada especificado y escribe una matriz JSON de herramientas (que contiene name , description y input_schema ) en el archivo de salida especificado.

2. Consulta la API antrópica:

A continuación, use el script token.sh para enviar estas definiciones de herramientas junto con un mensaje de ejemplo a la API de Anthropic. Necesitará una clave de API de Anthropic para este paso.

# Ensure you have jq installed
# Replace sk-ant-xxxxxxxx with your actual Anthropic API key
# Replace .tmp/tools.json with the path to the file generated in step 1
./token.sh -k sk-ant-xxxxxxxx -i .tmp/tools.json

El script generará la respuesta JSON de la API Anthropic, que incluye el recuento de tokens estimado para las herramientas proporcionadas y un mensaje de muestra en el campo usage.input_tokens .

Este proceso ayuda a comprender el costo del token asociado con el conjunto de herramientas proporcionado al modelo de lenguaje.

Portainer MCP

Portainer MCP

Descripción general

Instalación

Uso

Personalización de herramientas

Modo de solo lectura

Soporte de versiones de Portainer

Capacidades admitidas

Desarrollo

Estadísticas de código

Conteo de fichas

Related MCP Servers

mcp-server-docker

Sandbox MCP

MarineTraffic MCP Server

MCP Expr Lang

Appeared in Searches

New MCP Servers

MCP directory API