ZenML

Servidor MCP para ZenML

Este proyecto implementa un servidor Model Context Protocol (MCP) para interactuar con la API de ZenML.

¿Qué es MCP?

Model Context Protocol (MCP) es un protocolo abierto que estandariza cómo las aplicaciones proporcionan contexto a los modelos de lenguaje grandes (LLM). Actúa como un «puerto USB-C para aplicaciones de IA»: proporciona una forma estandarizada de conectar modelos de IA con distintas fuentes de datos y herramientas.

MCP sigue una arquitectura cliente-servidor en la que:

• Hosts MCP: programas como Claude Desktop o IDE que quieren acceder a datos mediante MCP
• Clientes MCP: clientes del protocolo que mantienen conexiones 1:1 con los servidores
• Servidores MCP: programas ligeros que exponen capacidades específicas mediante el protocolo estandarizado
• Fuentes de datos locales: los archivos, las bases de datos y los servicios de tu ordenador a los que los servidores MCP pueden acceder de forma segura
• Servicios remotos: sistemas externos disponibles a través de Internet a los que pueden conectarse los servidores MCP

¿Qué es ZenML?

ZenML es una plataforma de código abierto para crear y gestionar canalizaciones de ML e IA. Proporciona una interfaz unificada para gestionar datos, modelos y experimentos.

Para obtener más información, consulta el sitio web de ZenML y nuestra documentación.

Funciones

El servidor proporciona herramientas MCP para acceder a las funciones principales de lectura del servidor ZenML y obtener información actualizada sobre:

Entidades principales

• Usuarios: cuentas de usuario y permisos
• Stacks: configuraciones de infraestructura
• Componentes de stack: elementos individuales que componen un stack
• Flavors: tipos de componentes disponibles
• Conectores de servicio: autenticación en la nube

Ejecución de canalizaciones

• Canalizaciones: definiciones de canalizaciones
• Ejecuciones de canalización: historial y estado de ejecución
• Pasos de canalización: detalles, código y registros de cada paso
• Programaciones: programaciones de ejecución automatizadas
• Artefactos: metadatos sobre artefactos de datos (no los datos en sí)

Implementación y servicio

• Snapshots: configuraciones de canalización congeladas (el artefacto que define «qué ejecutar o servir»)
• Implementaciones: instancias de servicio en tiempo de ejecución con estado, URL y registros
• Servicios: endpoints de servicio de modelos

Organización y detección

• Proyectos: contenedores organizativos para los recursos de ZenML
• Etiquetas: etiquetas de metadatos transversales para facilitar la detección
• Builds: artefactos de compilación de canalizaciones con información de imágenes y código

Modelos

• Modelos: entradas del registro de modelos de ML
• Versiones de modelo: artefactos de modelos con control de versiones

API de compatibilidad (se recomienda la migración)

• Las plantillas de ejecución de canalización siguen disponibles en ZenML 0.97.0, mientras que se prefieren los Snapshots para los nuevos flujos de trabajo (consulta la guía de migración)

El servidor también permite activar nuevas ejecuciones de canalización mediante snapshots (opción preferida) o el parámetro obsoleto de activación basado en plantillas.

Nota: Mejoramos continuamente esta integración a partir de los comentarios de los usuarios. Únete a nuestra comunidad de Slack para compartir tu experiencia y ayudarnos a mejorarla aún más.

Perfiles de herramientas y política de escritura

El perfil predeterminado compact anuncia 16 herramientas. Siete herramientas genéricas cubren el catálogo de recursos, las lecturas, las mutaciones habituales y las acciones de ciclo de vida finitas:

Herramienta	Propósito
zenml_describe_resources	Detectar los tipos de recursos compatibles y los esquemas de operaciones acotados
zenml_list_resources	Enumerar un tipo de recurso con filtros validados y paginación
zenml_get_resource	Obtener un recurso, con el ámbito del elemento principal y del proyecto cuando sea necesario
zenml_create_resource	Crear un recurso compatible a partir de una carga útil tipada
zenml_update_resource	Actualizar un UUID de recurso exacto
zenml_delete_resource	Eliminar o archivar un UUID de recurso exacto
zenml_action_resource	Ejecutar una acción permitida de ciclo de vida o relación sin reintentos

Se mantienen nueve herramientas específicas porque proporcionan diagnósticos, contexto activo, registros o código transmitidos, ejecución de canalizaciones o una App interactiva:

• diagnose_zenml_setup
• get_active_user y get_active_project
• trigger_pipeline
• get_step_logs, get_step_code y get_deployment_logs
• open_pipeline_run_dashboard y open_run_activity_chart

get_step_logs devuelve como máximo 50,000 entradas, de la más antigua a la más reciente, con una marca possibly_truncated, además de un note que indica qué entradas faltan y por qué. Pasa tail para obtener solo las entradas más recientes. En los servidores ZenML 0.97+, pagina a través del almacén de registros; en 0.96 usa el endpoint antiguo de solicitud única.

Usa ZENML_MCP_PROFILE=legacy cuando un cliente existente aún dependa de los nombres antiguos específicos de entidad, como list_pipeline_runs. Esto conserva la capa de compatibilidad caracterizada de nombres de herramientas y esquemas para ZenML 0.97.0. No añade compatibilidad con versiones anteriores del servidor ZenML. Úsalo solo durante la migración: las formas de respuesta heredadas pueden exponer más metadatos operativos que las herramientas compactas, aunque el servidor omite de ambos perfiles la configuración que contiene credenciales y otros campos confidenciales.

El registro y el acceso de escritura son independientes:

Perfil	Política	Herramientas anunciadas
compact	read_write	16
compact	read_only	11
legacy	read_write	57
legacy	read_only	52

Establece ZENML_MCP_WRITE_POLICY=read_only para eliminar las cuatro herramientas genéricas de mutación y trigger_pipeline del descubrimiento y el despacho de MCP. El descubrimiento de recursos también omite los esquemas de creación, actualización, eliminación y acción. Se sigue aceptando la configuración anterior ZENML_MCP_READ_ONLY=true; los valores de política no válidos se cierran de forma segura y activan el modo de solo lectura. Un valor no válido de ZENML_MCP_PROFILE detiene el inicio con un error de configuración.

La versión 2.0.0 requiere MCP Python SDK 2.2.0 y ZenML 0.96.4. El perfil compacto es el nuevo predeterminado y supone un cambio incompatible en el descubrimiento para los clientes que llaman a nombres de herramientas específicos de entidad. Establece ZENML_MCP_PROFILE=legacy durante la migración de esos clientes y, después, cambia cada llamada a las herramientas genéricas de recursos.

Los resultados de las mutaciones distinguen entre los resultados completed, accepted y unknown. El servidor no reintenta una mutación después de que esta pueda haber llegado a ZenML. Si el resultado es aceptado o desconocido, sigue las instrucciones de conciliación de la respuesta antes de decidir si vuelves a llamar. Usa la lectura indicada por nombre cuando esté disponible. La creación de webhooks y la rotación de secretos pueden devolver un nuevo secreto de firma una sola vez; las lecturas posteriores lo omiten. Los esquemas de eliminación indican si una operación archiva metadatos, elimina metadatos, desprovisiona un recurso activo o puede eliminar datos de artefactos almacenados.

La primera versión 2.0 cubre las operaciones habituales para proyectos, stacks y componentes, flavors, servicios, canalizaciones y ejecuciones, snapshots y plantillas, implementaciones, artefactos y versiones, modelos y versiones, etiquetas, conectores, repositorios de código, webhooks, activadores, condiciones de espera e invocaciones de hooks. Los usuarios, las programaciones, los tipos de conectores de servicio, los secretos y las solicitudes de recursos tienen la cobertura de solo lectura que muestra zenml_describe_resources. Se excluyen la administración del plano de control de ZenML Cloud, la administración de Resource Manager, la administración de usuarios y credenciales, las operaciones CRUD de valores de secretos, el inicio de sesión y la verificación de conectores, los eventos de webhook sin procesar y las herramientas agregadas de depuración o linaje.

Inicia un flujo de trabajo genérico descubriendo el esquema preciso y, después, llamándolo:

zenml_describe_resources(resource_type="pipeline_run", operation="list")
zenml_list_resources(
    resource_type="pipeline_run",
    filters={"status": "completed", "sort_by": "desc:created"},
    page=1,
    size=10,
)

Las indicaciones y los recursos siguen disponibles en ambos perfiles. Las indicaciones de análisis, los endpoints acotados de esquemas de recursos y most_recent_runs son indicaciones o recursos MCP, no herramientas.

Compatibilidad con plantillas de ejecución

ZenML 0.97.0 conserva las API CRUD de plantillas de ejecución. Se prefieren los snapshots para los nuevos flujos de trabajo. La creación de canalizaciones mediante funciones de conveniencia y el parámetro de activación basado en plantillas están obsoletos. En el perfil heredado, get_run_template y list_run_templates siguen disponibles para los clientes existentes.

La entrada heredada tag se mantiene en list_run_templates por compatibilidad de esquema, pero ZenML 0.97.0 no tiene un filtro equivalente del lado del servidor. Un valor no nulo se rechaza antes de la llamada al SDK. El filtrado de snapshots por etiquetas sigue disponible.

Migración: plantillas de ejecución → Snapshots

¿Por qué este cambio? Los snapshots sustituyeron a las plantillas de ejecución como artefacto de canalización ejecutable preferido de ZenML. El SDK 0.97.0 sigue admitiendo las operaciones CRUD de plantillas de ejecución, mientras que el código nuevo debe usar snapshots.

Guía rápida de migración

Patrón heredado (plantillas)	Patrón compacto (snapshots)
list_run_templates()	zenml_list_resources(resource_type="snapshot", filters={"runnable": true, "named_only": true})
get_run_template(name)	zenml_get_resource(resource_type="snapshot", resource_id=id)
trigger_pipeline(template_id=...)	trigger_pipeline(snapshot_name_or_id=...)

Flujo de trabajo de ejemplo (primero snapshots)

1. Discover project context:
   → get_active_project()

2. Find runnable snapshots:
   → zenml_list_resources(resource_type="snapshot", filters={"runnable": true, "named_only": true})

3. Trigger a run:
   → trigger_pipeline(snapshot_name_or_id="my-snapshot")

4. Check deployments:
   → zenml_list_resources(resource_type="deployment", filters={"status": "running"})
   → get_deployment_logs(name_id_or_prefix="my-deployment", tail=100)

Para anular parámetros al activar un snapshot ejecutable, pasa una configuración de ejecución de ZenML (el snapshot en sí no cambia):

trigger_pipeline(
    snapshot_name_or_id="my-snapshot",
    run_configuration={
        "steps": {"train": {"parameters": {"learning_rate": 0.01}}},
        "enable_cache": False,
    },
)

Para los snapshots estáticos, anula los parámetros de los pasos como se muestra arriba. Las anulaciones de nivel superior run_configuration={"parameters": {...}} afectan a los parámetros de la función de canalización y solo son compatibles con snapshots dinámicos; ZenML las rechaza en los snapshots estáticos.

Nota: get_deployment_logs devuelve una salida acotada (100 líneas de forma predeterminada, máximo 1000, con un límite de 100KB) y requiere que esté instalada la integración de deployer correspondiente.

Configuración rápida mediante el panel (recomendado)

La forma más sencilla de configurar el servidor MCP de ZenML es desde la página de configuración de MCP del panel de ZenML.

Ve a Settings → MCP en el panel de ZenML para obtener:

• Fragmentos preconfigurados para la URL y las credenciales específicas de tu servidor
• Instalación con un clic mediante enlaces profundos para los IDE compatibles
• Configuraciones para copiar y pegar en VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex y otros
• Opciones de Docker y uv según tus preferencias

Usuarios de ZenML Pro

La página de configuración de MCP permite generar un token de acceso personal (PAT) con un solo clic. El token se incluye automáticamente en todos los fragmentos de configuración generados.

Usuarios de ZenML OSS

1. Primero, crea un token de cuenta de servicio desde Settings → Service Accounts
2. Pega el token en la página de configuración de MCP
3. Copia la configuración generada para tu IDE

---

¿Prefieres la configuración manual? Consulta las instrucciones detalladas a continuación.

MCP Apps (experimental)

¿Qué son las MCP Apps? Las MCP Apps son interfaces HTML interactivas que los servidores MCP pueden servir directamente a los clientes de IA. Se muestran en iframes aislados y pueden llamar a herramientas del servidor en ambas direcciones. Consulta el anuncio oficial para obtener todos los detalles.

Este servidor incluye dos MCP Apps experimentales:

App	Herramienta	Descripción
Panel de ejecuciones de canalización	open_pipeline_run_dashboard	Tabla interactiva de las ejecuciones de canalización recientes con estado, detalles de los pasos y registros
Gráfico de actividad de ejecuciones	open_run_activity_chart	Gráfico de barras de la actividad de las ejecuciones de canalización durante los últimos 30 días, desglosada por estado

Estas apps se incluyen como ejemplos de prueba de concepto. Agradecemos los comentarios y las contribuciones para crear más MCP Apps. Esta función aún está en sus primeras etapas, así que habrá que ver cómo evoluciona. Esperamos ofrecer una compatibilidad más completa en el futuro.

Clientes compatibles

Las MCP Apps requieren el transporte Streamable HTTP (no stdio). Actualmente, los siguientes clientes son compatibles con MCP Apps:

• ✅ VS Code (edición Insiders)
• ✅ Goose
• ✅ ChatGPT (próximamente)
• ⚠️ Claude Desktop: a finales de enero de 2026, todavía no muestra Apps.
• ⚠️ Claude.ai (web): a finales de enero de 2026, todavía no muestra Apps.

Nota: No pudimos probar a fondo Claude Desktop ni Claude.ai en el momento de redactar este documento. Si encuentras problemas, infórmanos.

Ejecutar MCP Apps con Docker

Las MCP Apps usan Streamable HTTP. Mantén el puerto del contenedor enlazado a loopback y coloca un proxy inverso autenticado o un servicio de acceso con reconocimiento de identidad delante antes de permitir el acceso remoto. La validación de Host y Origin protege contra el reenlace de DNS; no autentica a quienes realizan las llamadas.

1. Compila y ejecuta el contenedor de Docker:

docker build -t mcp-zenml:apps .

docker run --rm -d --name mcp-zenml-apps -p 127.0.0.1:8001:8001 \
  -e ZENML_STORE_URL="https://your-zenml-server.example.com" \
  -e ZENML_STORE_API_KEY="your-api-key" \
  -e ZENML_MCP_PROFILE="compact" \
  -e ZENML_MCP_WRITE_POLICY="read_write" \
  -e ZENML_ACTIVE_PROJECT_ID="your-project-id" \
  mcp-zenml:apps --transport streamable-http --host 0.0.0.0 --port 8001 \
  --disable-dns-rebinding-protection

2. Configura el acceso remoto autenticado:

Crea un túnel de Cloudflare con nombre, un Tailscale Funnel con controles de acceso o un proxy inverso autenticado equivalente. Dirige su origen privado a http://127.0.0.1:8001, exige una identidad o credencial de servicio para el host público y permite que solo las solicitudes autenticadas lleguen al origen. Configura tu cliente MCP para que use el flujo OAuth o los encabezados de autorización compatibles con el proveedor.

Antes de añadir credenciales de ZenML al contenedor, verifica que una solicitud no autenticada no pueda llegar a MCP:

curl -i https://mcp.example.com/mcp

La respuesta debe ser 401, 403 del proveedor de acceso o una redirección al inicio de sesión. Una respuesta JSON-RPC o MCP significa que el perímetro está abierto y debe corregirse primero.

3. Conecta tu cliente autenticado:

{
	"servers": {
		"ZenML": {
			"url": "https://mcp.example.com/mcp",
			"type": "http"
		}
	},
	"inputs": []
}

• Pídele a la IA que «abra el panel de ejecuciones de canalizaciones» o «muestre el gráfico de actividad de ejecuciones»

Notas importantes:

• Se requiere ZENML_ACTIVE_PROJECT_ID; sin él, las herramientas de ejecución de canalizaciones fallarán con «No project is currently set as active»
• --disable-dns-rebinding-protection solo es apropiado cuando el proxy autenticado valida el host público y el puerto del contenedor permanece limitado a loopback
• Limita la clave de API de ZenML a los permisos que necesite el cliente MCP; usa ZENML_MCP_WRITE_POLICY=read_only para clientes que solo necesiten inspeccionar

Pruebas y control de calidad

Este proyecto incluye pruebas automatizadas para garantizar que el servidor MCP siga funcionando:

• 🔄 Pruebas de humo automatizadas: Una prueba de humo exhaustiva se ejecuta cada 3 días mediante GitHub Actions
• 🚨 Creación de incidencias: Las pruebas fallidas crean automáticamente incidencias de GitHub con información detallada para la depuración
• ⚡ CI rápido: Usa UV con almacenamiento en caché para instalar dependencias y ejecutar pruebas rápidamente
• 🧪 Pruebas manuales: Puedes ejecutar la prueba de humo localmente con uv run scripts/test_mcp_server.py server/zenml_server.py

Las pruebas automatizadas verifican:

• La conexión y el protocolo de enlace del protocolo MCP
• La inicialización del servidor y la detección de herramientas
• La funcionalidad básica de las herramientas (cuando el servidor ZenML está accesible)
• La enumeración de recursos y prompts
• diagnose_zenml_setup devuelve diagnósticos estructurados incluso en entornos restringidos

La CI sin credenciales cubre todos los adaptadores mediante el protocolo MCP. La CI de PR y de versiones también inicia un servidor OSS de ZenML 0.97.0 nuevo en una dirección de loopback y ejecuta comprobantes de operaciones CRUD persistentes y de aislamiento de proyectos con el mismo nombre. El servidor usa una configuración y una base de datos temporales que se eliminan al finalizar el trabajo; no se requiere ningún entorno del repositorio, ejecutor autohospedado ni credencial de ZenML.

El servidor OSS local de ZenML desactiva la autenticación y su almacén SQL no admite la repetición de canalizaciones ni la infraestructura de despliegue externa. Por lo tanto, los comprobantes de acceso restringido y de activadores, repetición, despliegue, condiciones de espera y solicitudes de recursos con funciones habilitadas siguen siendo puertas de acceso optativas independientes. Requieren ZENML_MCP_RESTRICTED_INTEGRATION=1 con ZENML_MCP_RESTRICTED_API_KEY, o ZENML_MCP_ACTION_INTEGRATION=1 con los UUID exactos de los accesorios desechables en ZENML_MCP_ACTION_FIXTURE, respectivamente. Omitir una prueba por una puerta de acceso no demuestra que esas capacidades hayan superado la prueba. Un operador puede establecer ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 para que la falta de una puerta de acceso optativa provoque un fallo. El aprovisionamiento de infraestructura en la nube nunca forma parte de la ejecución de pruebas predeterminada.

Depuración con MCP Inspector

Para la depuración interactiva, usa MCP Inspector, una herramienta web que te permite probar herramientas MCP en tiempo real:

# Using .env.local (recommended for development)
cp .env.local.example .env.local  # Then edit with your credentials
source .env.local && npx @modelcontextprotocol/inspector \
  -e ZENML_STORE_URL=$ZENML_STORE_URL \
  -e ZENML_STORE_API_KEY=$ZENML_STORE_API_KEY \
  -- uv run server/zenml_server.py

Se abrirá una interfaz web con tus credenciales ya rellenadas. Solo tienes que hacer clic en Connect y usar la pestaña Tools para probar cualquier herramienta de forma interactiva.

Consulta CLAUDE.md para obtener instrucciones de depuración más detalladas.

Privacidad y analítica

El servidor MCP de ZenML recopila datos de uso anónimos para ayudarnos a mejorar el producto.

Recopilamos:

• Qué herramientas se usan y con qué frecuencia
• Tasas y tipos de errores (solo el tipo de error, no los mensajes)
• Información básica del entorno (sistema operativo, versión de Python y si se ejecuta en Docker/CI)
• Duración de la sesión y patrones de uso de las herramientas

NO recopilamos:

• La URL de tu servidor ZenML ni tu clave de API
• Nombres de canalizaciones, nombres de modelos ni datos empresariales
• Mensajes de error ni trazas de pila
• Información de identificación personal

Para desactivar la analítica:

# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false

# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true

Para depuración/pruebas (registra eventos en stderr en lugar de enviarlos):

export ZENML_MCP_ANALYTICS_DEV=true

Para usuarios de Docker: Puedes establecer ZENML_MCP_ANALYTICS_ID (debe ser un UUID válido) para mantener un ID anónimo coherente entre reinicios del contenedor. Si no lo estableces y el sistema de archivos del contenedor no puede conservar el archivo del ID de analítica, el servidor recurrirá a un UUID anónimo determinista derivado de un hash de ZENML_STORE_URL (la URL en sí nunca se envía como propiedad de un evento).

Opciones adicionales de analítica:

• ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S — tiempo máximo (en segundos) para vaciar la analítica de forma síncrona durante el apagado (valor predeterminado: 1.0)

Nota sobre el seguimiento del apagado: Los eventos de apagado se envían de forma síncrona con un tiempo de espera limitado para maximizar la fiabilidad de entrega. Sin embargo, si se termina un contenedor con SIGKILL (por ejemplo, docker kill), los controladores de apagado no pueden ejecutarse; es una limitación de Docker/OS, no un error.

Validación al iniciar

Puedes habilitar una comprobación de diagnóstico ligera al iniciar:

# Print warnings but start normally
uv run server/zenml_server.py --startup-validation warn

# Exit non-zero if required setup is missing (useful in Docker/CI)
uv run server/zenml_server.py --startup-validation strict

También puedes establecerlo mediante la variable de entorno: ZENML_MCP_STARTUP_VALIDATION=warn.

La herramienta diagnose_zenml_setup también está disponible como herramienta MCP para la resolución de problemas en tiempo de ejecución; funciona incluso cuando el SDK de ZenML no está instalado o faltan variables de entorno.

Configuración manual

Requisitos previos

Necesitarás acceso a un servidor ZenML desplegado. Si no tienes uno, puedes registrarte para una prueba gratuita en ZenML Pro y nos encargaremos del despliegue.

Consejo: Cuando tengas un servidor ZenML, consulta la página de configuración de MCP en tu panel para disfrutar de la configuración más sencilla.

Compatibilidad: La versión actual se ha probado con ZenML 0.97.0. Si usas una versión anterior de ZenML, utiliza una versión anterior de este servidor MCP.

También es probable que necesites tener uv instalado localmente. Para obtener más información, consulta la documentación de uv. Recomendamos instalarlo mediante su script de instalación o con brew si usas un Mac. (Técnicamente no lo necesitas, pero facilita la instalación y la configuración).

También tendrás que clonar este repositorio en alguna ubicación local:

git clone https://github.com/zenml-io/mcp-zenml.git

Tu archivo de configuración de MCP

El archivo de configuración de MCP es un archivo JSON que indica al cliente MCP cómo conectarse a tu servidor MCP. Cada cliente MCP puede usarlo o especificarlo de forma distinta. Dos clientes MCP de uso habitual son Claude Desktop y Cursor, para los que ofrecemos instrucciones de instalación a continuación.

Deberás especificar tu servidor MCP de ZenML con el siguiente formato:

{
    "mcpServers": {
        "zenml": {
            "command": "/usr/local/bin/uv",
            "args": ["run", "path/to/server/zenml_server.py"],
            "env": {
                "LOGLEVEL": "WARNING",
                "NO_COLOR": "1",
                "ZENML_LOGGING_COLORS_DISABLED": "true",
                "ZENML_LOGGING_VERBOSITY": "WARN",
                "ZENML_ENABLE_RICH_TRACEBACK": "false",
                "ZENML_MCP_PROFILE": "compact",
                "ZENML_MCP_WRITE_POLICY": "read_write",
                "PYTHONUNBUFFERED": "1",
                "PYTHONIOENCODING": "UTF-8",
                "ZENML_STORE_URL": "https://your-zenml-server-goes-here.com",
                "ZENML_STORE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Cuando se proporciona ZENML_STORE_API_KEY, el servidor MCP mantiene en memoria las credenciales de ZenML y no lee ni actualiza las credenciales guardadas por zenml login. Esto se aplica a las ejecuciones directas de Python, las extensiones MCPB y Docker. Las conexiones sin una clave de API pueden seguir usando el inicio de sesión guardado en tu terminal. Reinicia el servidor MCP después de cambiar su clave de API; un chat nuevo por sí solo podría reutilizar el proceso del servidor en ejecución.

Hay cuatro valores ficticios que tendrás que reemplazar:

• la ruta a tu instalación local de uv (la ruta indicada arriba es la que tendría en un Mac si lo instalaras mediante brew)
• la ruta al archivo zenml_server.py (este es el archivo que se ejecutará al conectarte al servidor MCP). Este archivo se encuentra en la raíz de este repositorio. Deberás especificar la ruta completa exacta a este archivo.
• la URL del servidor ZenML (es la URL de tu servidor ZenML. Puedes encontrarla en la interfaz de usuario de ZenML Cloud). Tendrá un aspecto similar a https://d534d987a-zenml.cloudinfra.zenml.io.
• la clave de API del servidor ZenML (es la clave de API de tu servidor ZenML. Puedes encontrarla en la interfaz de usuario de ZenML Cloud o https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account para saber cómo crear una. Para el servidor MCP de ZenML, recomendamos usar una cuenta de servicio).

Puedes cambiar la forma de ejecutar el archivo Python del servidor MCP, pero usar uv probablemente sea la opción más sencilla, ya que se encarga del entorno y de instalar las dependencias.

Instalación para usar con Claude Desktop

Alternativa rápida: Usa la página de configuración de MCP en tu panel de ZenML (Settings → MCP) para obtener instrucciones de instalación preconfiguradas y enlaces directos para Claude Desktop.

Deberás tener instalada la versión más reciente de Claude Desktop.

Solo tienes que abrir el menú Settings y arrastrar el archivo mcp-zenml.mcpb desde la raíz de este repositorio hasta el menú. Se te guiará por el proceso de instalación y configuración. Tendrás que añadir la URL y la clave de API de tu servidor ZenML.

Nota: Los paquetes MCP (.mcpb) sustituyen al formato anterior de Desktop Extensions (.dxt); los archivos .dxt existentes siguen funcionando en Claude Desktop.

Opcional: Mejorar la visualización de los resultados de las herramientas de ZenML

Para disfrutar de una mejor experiencia con los resultados de las herramientas de ZenML, puedes configurar Claude para que muestre las respuestas JSON en un formato más legible. En Claude Desktop, ve a Settings → Profile y, en la sección «What personal preferences should Claude consider in responses?», añade algo como lo siguiente (¡o usa estas palabras exactas!):

When using zenml tools which return JSON strings and you're asked a question, you might want to consider using markdown tables to summarize the results or make them easier to view!

Esto animará a Claude a presentar los resultados de las herramientas de ZenML en tablas Markdown, lo que hará que la información sea mucho más fácil de leer y entender.

Instalación para usar con Cursor

Alternativa rápida: La página de configuración de MCP en tu panel de ZenML (Settings → MCP) puede generar el contenido exacto de mcp.json con tus credenciales ya rellenadas.

Deberás tener Cursor instalado.

Cursor funciona de forma ligeramente distinta a Claude Desktop: la configuración se especifica por repositorio. Esto significa que, si quieres usar el servidor MCP de ZenML en varios repositorios, tendrás que especificar el archivo de configuración en cada uno.

Para configurarlo en un solo repositorio, tendrás que:

• crear una carpeta .cursor en la raíz del repositorio
• crear dentro un archivo mcp.json con el contenido anterior
• ir a la configuración de Cursor y hacer clic en el servidor ZenML para «habilitarlo».

Según nuestra experiencia, a veces aparece un indicador de error rojo aunque esté funcionando. Puedes probarlo chateando en la ventana de chat de Cursor. Te indicará si puede acceder a las herramientas de ZenML.

Imagen de Docker

Puedes ejecutar el servidor como un contenedor de Docker. El proceso se comunica mediante stdio, por lo que esperará a que se conecte un cliente MCP. Pasa tus credenciales de ZenML mediante variables de entorno.

Imágenes precompiladas (Docker Hub)

Descarga la imagen multiarquitectura más reciente:

docker pull zenmldocker/mcp-zenml:latest

Las versiones publicadas llevan la etiqueta X.Y.Z:

docker pull zenmldocker/mcp-zenml:2.0.0

Ejecuta el servidor con tus credenciales de ZenML (modo stdio):

docker run -i --rm \
  -e ZENML_STORE_URL="https://your-zenml-server.example.com" \
  -e ZENML_STORE_API_KEY="your-api-key" \
  zenmldocker/mcp-zenml:latest

Configuración canónica de MCP con Docker

{
  "mcpServers": {
    "zenml": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ZENML_STORE_URL=https://...",
        "-e", "ZENML_STORE_API_KEY=ZENKEY_...",
        "-e", "ZENML_ACTIVE_PROJECT_ID=...",
        "-e", "ZENML_MCP_PROFILE=compact",
        "-e", "ZENML_MCP_WRITE_POLICY=read_write",
        "-e", "LOGLEVEL=WARNING",
        "-e", "NO_COLOR=1",
        "-e", "ZENML_LOGGING_COLORS_DISABLED=true",
        "-e", "ZENML_LOGGING_VERBOSITY=WARN",
        "-e", "ZENML_ENABLE_RICH_TRACEBACK=false",
        "-e", "PYTHONUNBUFFERED=1",
        "-e", "PYTHONIOENCODING=UTF-8",
        "zenmldocker/mcp-zenml:latest"
      ]
    }
  }
}

Compilar localmente

Desde la raíz del repositorio:

docker build -t zenmldocker/mcp-zenml:local .

Ejecuta la imagen compilada localmente:

docker run -i --rm \
  -e ZENML_STORE_URL="https://your-zenml-server.example.com" \
  -e ZENML_STORE_API_KEY="your-api-key" \
  zenmldocker/mcp-zenml:local

Paquetes MCP (.mcpb)

Este proyecto usa paquetes MCP (.mcpb), sucesores de Desktop Extensions (DXT) de Anthropic. Los paquetes MCP incluyen un servidor MCP completo (con sus dependencias) en un solo archivo con una configuración fácil de usar.

Nota sobre el cambio de nombre: Los paquetes MCP sustituyen al formato anterior .dxt. Claude Desktop sigue siendo compatible con los archivos .dxt existentes, pero ahora distribuimos mcp-zenml.mcpb y recomendamos usarlo de ahora en adelante.

El archivo mcp-zenml.mcpb en la raíz del repositorio usa el entorno de ejecución UV de MCPB 0.4. El host instala las dependencias de Python fijadas para el sistema operativo actual, por lo que el mismo paquete funciona en macOS, Windows y Linux sin incluir extensiones nativas específicas de cada plataforma. La primera vez, la instalación necesita acceso a la red para que UV resuelva el entorno incluido. Las compilaciones del paquete reutilizan el mcpb-uv.lock confirmado y resuelven su grafo de dependencias de Python en modo sin conexión. La lista de dependencias del paquete proviene de [project].dependencies en pyproject.toml. Después de cambiar esa lista, establece MCPB_REFRESH_LOCK=1 para volver a resolver en línea y conservar todas las versiones fijadas que sigan siendo compatibles; MCPB_REFRESH_LOCK=upgrade actualiza todas las versiones fijadas a la más reciente.

Al arrastrar y soltar el archivo .mcpb en la configuración de Claude Desktop, se gestionan automáticamente:

• La instalación de dependencias del entorno de ejecución
• La gestión segura de la configuración
• La compatibilidad multiplataforma
• Un proceso de configuración sencillo

Para obtener más información, consulta el anuncio de Anthropic sobre las extensiones de escritorio (DXT) y las directrices relacionadas sobre el empaquetado de MCP en su documentación: https://www.anthropic.com/engineering/desktop-extensions

Publicado en el registro de MCP de Anthropic

Este servidor MCP está publicado en el registro oficial de MCP de Anthropic y es detectable por los hosts compatibles. En cada versión etiquetada, nuestro CI actualiza la entrada del registro mediante la CLI mcp-publisher del registro, usando GitHub OIDC, para que puedas instalar o descubrir el servidor MCP de ZenML directamente desde cualquier lugar donde se admita el registro (p. ej., el catálogo de extensiones de Claude Desktop).

• Siempre actualizado: la entrada del registro se actualiza con cada versión a partir de manifest.json y server.json del commit etiquetado.
• Métodos de instalación alternativos: también puedes instalarlo localmente mediante el paquete .mcpb (consulta más arriba) o ejecutar la imagen de Docker.

Obtén más información sobre el registro aquí:

• Registro de MCP de Anthropic (repositorio de la comunidad): https://github.com/modelcontextprotocol/registry