ZenML

Servidor MCP para ZenML

Este proyecto implementa un servidor de Protocolo de Contexto de Modelos (MCP) para interactuar con la API de ZenML.

¿Qué es MCP?

El Protocolo de Contexto de Modelos (MCP) es un protocolo abierto que estandariza cómo las aplicaciones proporcionan contexto a los Modelos de Lenguaje de Gran Escala (LLMs). Actúa como un "puerto USB-C para aplicaciones de IA": proporciona una forma estandarizada de conectar modelos de IA a diferentes fuentes de datos y herramientas.

MCP sigue una arquitectura cliente-servidor donde:

• Hosts MCP: Programas como Claude Desktop o IDEs que quieren acceder a datos a través de MCP
• Clientes MCP: Clientes de protocolo que mantienen conexiones 1:1 con servidores
• Servidores MCP: Programas ligeros que exponen capacidades específicas a través del protocolo estandarizado
• Fuentes de Datos Locales: Archivos, bases de datos y servicios de tu computadora a los que los servidores MCP pueden acceder de forma segura
• Servicios Remotos: Sistemas externos disponibles a través de internet a los que los servidores MCP pueden conectarse

¿Qué es ZenML?

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

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

Características

El servidor proporciona herramientas MCP para acceder a la funcionalidad principal de lectura del servidor ZenML, ofreciendo una forma de obtener información en vivo sobre:

Entidades Principales

• Usuarios - cuentas de usuario y permisos
• Stacks - configuraciones de infraestructura
• Componentes de Stack - bloques de construcción individuales del stack
• Sabores - tipos de componentes disponibles
• Conectores de Servicio - autenticación en la nube

Ejecución de Pipelines

• Pipelines - definiciones de pipelines
• Ejecuciones de Pipelines - historial de ejecución y estado
• Pasos de Pipelines - detalles de pasos individuales, código y registros
• Programaciones - programaciones de ejecución automática
• Artefactos - metadatos sobre artefactos de datos (no los datos en sí)

Despliegue y Servicio

• Instantáneas - configuraciones de pipeline congeladas (el artefacto de "qué ejecutar/servir")
• Despliegues - instancias de servicio en tiempo de ejecución con estado, URL y registros
• Servicios - endpoints de servicio de modelos

Organización y Descubrimiento

• Proyectos - contenedores organizativos para recursos de ZenML
• Etiquetas - etiquetas de metadatos transversales para descubrimiento
• Builds - artefactos de build de pipelines con información de imagen y código

Modelos

• Modelos - entradas del registro de modelos de ML
• Versiones de Modelos - artefactos de modelos versionados

APIs de Compatibilidad (se recomienda migración)

• Plantillas de ejecución de pipelines permanecen disponibles en ZenML 0.97.0, mientras que Instantáneas son preferidas para nuevos flujos de trabajo (consulta la Guía de Migración)

El servidor también te permite activar nuevas ejecuciones de pipelines usando instantáneas (preferido) o el parámetro de activación basado en plantillas, que está obsoleto.

Nota: Estamos mejorando continuamente esta integración basándonos en 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 compact predeterminado anuncia 16 herramientas. Siete herramientas genéricas cubren el catálogo de recursos, lecturas, mutaciones ordinarias y acciones de ciclo de vida finitas:

Herramienta	Propósito
zenml_describe_resources	Descubrir tipos de recursos admitidos y esquemas de operación acotados
zenml_list_resources	Listar un tipo de recurso con filtros validados y paginación
zenml_get_resource	Obtener un recurso, con alcance de padre y proyecto donde sea necesario
zenml_create_resource	Crear un recurso admitido 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 de ciclo de vida o relación en lista blanca sin reintentos

Nueve herramientas enfocadas permanecen porque proporcionan diagnósticos, contexto activo, registros o código en streaming, ejecución de pipelines o una aplicación 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, las más antiguas primero, con un indicador 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 servidores ZenML 0.97+, recorre el almacén de registros; en 0.96 usa el endpoint de solicitud única más antiguo.

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 de nombres de herramientas y esquemas caracterizada para ZenML 0.97.0. No agrega soporte para versiones de servidor ZenML más antiguas. Ú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 la configuración que contiene credenciales y otros campos sensibles de ambos perfiles.

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 de mutación genéricas y trigger_pipeline del descubrimiento y despacho de MCP. El descubrimiento de recursos también omite los esquemas de creación, actualización, eliminación y acción. La configuración más antigua ZENML_MCP_READ_ONLY=true sigue siendo aceptada; los valores de política inválidos fallan de forma segura al modo de solo lectura. Un ZENML_MCP_PROFILE inválido 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 es un cambio de descubrimiento importante para clientes que llaman nombres de herramientas específicos de entidad. Establece ZENML_MCP_PROFILE=legacy mientras migras esos clientes, luego mueve cada llamada a las herramientas de recursos genéricos.

Los resultados de mutación distinguen los resultados completed, accepted y unknown. El servidor no reintenta una mutación después de que pueda haber llegado a ZenML. Para un resultado aceptado o desconocido, sigue las instrucciones de reconciliación en la respuesta antes de decidir si llamar de nuevo. Usa la lectura nombrada cuando haya una disponible. La creación de webhooks y la rotación de secretos pueden devolver un secreto de firma nuevo una vez; las lecturas posteriores lo omiten. Los esquemas de eliminación indican si una operación archiva metadatos, elimina metadatos, desaprovisiona un recurso en vivo o puede eliminar datos de artefactos almacenados.

La primera versión 2.0 cubre operaciones ordinarias para proyectos, stacks y componentes, sabores, servicios, pipelines y ejecuciones, instantáneas y plantillas, despliegues, artefactos y versiones, modelos y versiones, etiquetas, conectores, repositorios de código, webhooks, disparadores, condiciones de espera e invocaciones de hooks. Usuarios, programaciones, tipos de conectores de servicio, secretos y solicitudes de recursos tienen la cobertura de solo lectura que se muestra en zenml_describe_resources. Excluye la administración del plano de control de ZenML Cloud, la administración de Resource Manager, la administración de usuarios y credenciales, CRUD de valores de secretos, inicio de sesión y verificación de conectores, eventos de webhook sin procesar y herramientas agregadas de depuración o linaje.

Inicia un flujo de trabajo genérico descubriendo el esquema preciso y luego 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,
)

Los prompts y recursos permanecen disponibles en ambos perfiles. Los prompts de análisis, los endpoints de esquema de recursos acotados y most_recent_runs son prompts o recursos de MCP en lugar de herramientas.

Compatibilidad de plantillas de ejecución

ZenML 0.97.0 conserva las APIs CRUD de plantillas de ejecución. Las instantáneas son preferidas para nuevos flujos de trabajo. La creación conveniente de pipelines y el parámetro de activación basado en plantillas están obsoletos. En el perfil heredado, get_run_template y list_run_templates permanecen disponibles para clientes existentes.

La entrada heredada tag permanece en list_run_templates para compatibilidad de esquemas, pero ZenML 0.97.0 no tiene un filtro de servidor equivalente. Un valor no nulo es rechazado antes de la llamada al SDK. El filtrado por etiquetas de instantáneas sigue disponible.

Migración: Plantillas de Ejecución → Instantáneas

¿Por qué el cambio? Las instantáneas reemplazaron a las plantillas de ejecución como el artefacto de pipeline ejecutable preferido de ZenML. El SDK 0.97.0 aún admite CRUD de plantillas de ejecución, mientras que el código nuevo debería usar instantáneas.

Guía de Migración Rápida

Patrón Heredado (Plantillas)	Patrón Compacto (Instantáneas)
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=...)

Ejemplo de Flujo de Trabajo (Primero Instantáneas)

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)

Nota: get_deployment_logs devuelve una salida acotada (100 líneas por defecto, máximo 1000, limitado a 100KB) y requiere que la integración de deployer apropiada esté instalada.

Configuración Rápida a través del Dashboard (Recomendado)

La forma más fácil de configurar el Servidor MCP de ZenML es a través de la página de Configuración de MCP de tu dashboard de ZenML.

Navega a Configuración → MCP en tu dashboard de ZenML para obtener:

• Fragmentos preconfigurados para tu URL de servidor y credenciales específicas
• Instalación con un clic a través de enlaces profundos para IDEs compatibles
• Configuraciones de copiar y pegar para VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex y más
• Opciones de Docker y uv según tu preferencia

Usuarios de ZenML Pro

La página de Configuración de MCP te 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 a través de Configuración → Cuentas de Servicio
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.

Aplicaciones MCP (Experimentales)

¿Qué son las Aplicaciones MCP? Las Aplicaciones MCP son UIs HTML interactivas que los servidores MCP pueden servir directamente en clientes de IA. Se renderizan en iframes aislados y pueden llamar herramientas del servidor de forma bidireccional. Consulta el anuncio oficial para más detalles.

Este servidor incluye dos Aplicaciones MCP experimentales:

Aplicación	Herramienta	Descripción
Panel de Ejecuciones de Pipelines	open_pipeline_run_dashboard	Tabla interactiva de ejecuciones de pipelines recientes con estado, detalles de pasos y registros
Gráfico de Actividad de Ejecuciones	open_run_activity_chart	Gráfico de barras de la actividad de ejecuciones de pipelines en los últimos 30 días con desglose por estado

Estas aplicaciones se incluyen como ejemplos de prueba de concepto. Agradecemos comentarios y contribuciones para más Aplicaciones MCP. Aún es temprano para esta nueva característica, así que tendremos que ver cómo evoluciona. Esperamos brindarle un soporte más completo en el futuro.

Clientes Compatibles

Las Aplicaciones MCP requieren transporte HTTP Streamable (no stdio). Los siguientes clientes actualmente admiten Aplicaciones MCP:

• ✅ VS Code (Edición Insiders)
• ✅ Goose
• ✅ ChatGPT (próximamente)
• ⚠️ Claude Desktop -- a finales de enero de 2026, aún no renderiza Aplicaciones.
• ⚠️ Claude.ai (web) — a finales de enero de 2026, aún no renderiza Aplicaciones.

Nota: No pudimos probar a fondo con Claude Desktop o Claude.ai al momento de escribir esto. Si encuentras problemas, por favor repórtalos.

Ejecutar Aplicaciones MCP con Docker

Las Aplicaciones MCP usan HTTP Streamable. Mantén el puerto del contenedor vinculado a loopback y coloca un proxy inverso autenticado o un servicio de acceso consciente de identidad frente a él antes de permitir el acceso remoto. La validación de Host y Origin protege contra el rebinding de DNS; no autentican a los llamantes.

1. Construye y ejecuta el contenedor 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 Cloudflare Tunnel con nombre, Tailscale Funnel con controles de acceso, o un proxy inverso autenticado equivalente. Apunta su origen privado a http://127.0.0.1:8001, exige una identidad o credencial de servicio para el nombre de host público, y pasa solo solicitudes autenticadas al origen. Configura tu cliente MCP para usar el flujo OAuth compatible del proveedor o los encabezados de autorización.

Antes de agregar 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 el 401, 403 o la redirección de inicio de sesión del proveedor de acceso. 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": []
}

• Pide a la IA que "abra el panel de ejecuciones de pipelines" o "muestre el gráfico de actividad de ejecuciones"

Notas importantes:

• ZENML_ACTIVE_PROJECT_ID es obligatorio — sin él, las herramientas de ejecución de pipelines fallarán con "No hay ningún proyecto establecido como activo"
• --disable-dns-rebinding-protection solo es apropiado cuando el proxy autenticado valida el host público y el puerto del contenedor permanece solo en loopback
• Restringe la clave API de ZenML a los permisos que el cliente MCP necesite; usa ZENML_MCP_WRITE_POLICY=read_only para clientes de solo inspección

Pruebas y Aseguramiento de Calidad

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

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

Las pruebas automatizadas verifican:

• Conexión y handshake del protocolo MCP
• Inicialización del servidor y descubrimiento de herramientas
• Funcionalidad básica de herramientas (cuando el servidor ZenML es accesible)
• Enumeración de recursos y prompts
• diagnose_zenml_setup devuelve diagnósticos estructurados incluso en entornos restringidos

La CI sin credenciales cubre cada adaptador a través del protocolo MCP. La CI de PR y releases también inicia un servidor OSS nuevo de ZenML 0.97.0 en una dirección loopback y ejecuta recibos de CRUD persistidos y de aislamiento de proyectos con el mismo nombre. El servidor usa una configuración y base de datos temporales que se eliminan cuando el job termina; no se requiere ningún entorno de repositorio, runner autoalojado ni credencial de ZenML.

El servidor OSS local de ZenML deshabilita la autenticación y su almacén SQL no admite la reproducción de pipelines ni la infraestructura de despliegue externa. El acceso restringido y los recibos de activación, reproducción, despliegue, condiciones de espera y solicitudes de recursos habilitados por funciones siguen siendo compuertas de participación separadas. Requieren ZENML_MCP_RESTRICTED_INTEGRATION=1 con ZENML_MCP_RESTRICTED_API_KEY, o ZENML_MCP_ACTION_INTEGRATION=1 con los UUIDs exactos de fixtures desechables en ZENML_MCP_ACTION_FIXTURE, respectivamente. Un salto con compuerta no es evidencia de que esas capacidades hayan pasado. Un operador puede establecer ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 para convertir una compuerta de participación faltante en un fallo. El aprovisionamiento de infraestructura en la nube nunca es parte de la ejecución de pruebas predeterminada.

Depuración con MCP Inspector

Para depuración interactiva, usa el MCP Inspector — una herramienta basada en 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

Esto abre una interfaz web con tus credenciales prellenadas — solo haz clic en Conectar y usa la pestaña Herramientas para probar cualquier herramienta de forma interactiva.

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

Privacidad y Analítica

El Servidor MCP de ZenML recopila analítica de uso anónima para ayudarnos a mejorar el producto.

Rastreamos:

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

NO recopilamos:

• Tu URL del servidor ZenML o clave API
• Nombres de pipelines, nombres de modelos o cualquier dato comercial
• Mensajes de error o trazas de pila
• Ninguna información de identificación personal

Para deshabilitar 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 consistente entre reinicios del contenedor. Si no lo estableces y el sistema de archivos del contenedor no puede persistir el archivo de ID de analítica, el servidor recurre 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 evento).

Opciones adicionales de analítica:

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

Nota sobre el seguimiento de apagado: Los eventos de apagado se envían de forma síncrona con un tiempo de espera limitado para una mejor confiabilidad de entrega. Sin embargo, si un contenedor se mata con SIGKILL (por ejemplo, docker kill), los manejadores de apagado no pueden ejecutarse — esto es una limitación de Docker/SO, no un error.

Validación de Inicio

Puedes habilitar una verificación de diagnóstico de inicio ligera:

# 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 establecer esto mediante una 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 tener acceso a un servidor ZenML desplegado. Si no tienes uno, puedes registrarte para una prueba gratuita en ZenML Pro y nosotros gestionaremos el despliegue por ti.

Consejo: Una vez que tengas un servidor ZenML, consulta la página de Configuración de MCP en tu panel para la experiencia de configuración más fácil.

Compatibilidad: La versión actual está probada contra ZenML 0.97.0. Si estás ejecutando una versión anterior de ZenML, usa una versión anterior de este servidor MCP.

También necesitarás (probablemente) tener uv instalado localmente. Para más información, consulta la documentación de uv. Recomendamos la instalación mediante su script de instalación o mediante brew si usas una Mac. (Técnicamente no lo necesitas, pero facilita la instalación y configuración).

También necesitarás clonar este repositorio en algún lugar localmente:

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

Tu archivo de configuración MCP

El archivo de configuración MCP es un archivo JSON que le dice al cliente MCP cómo conectarse a tu servidor MCP. Diferentes clientes MCP lo usarán o especificarán de manera diferente. Dos clientes MCP de uso común son Claude Desktop y Cursor, para los cuales proporcionamos instrucciones de instalación a continuación.

Necesitarás especificar tu servidor MCP de ZenML en 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"
            }
        }
    }
}

Hay cuatro valores ficticios que necesitarás reemplazar:

• la ruta a tu uv instalado localmente (la ruta listada arriba es donde estaría en una Mac si lo instalaste mediante brew)
• la ruta al archivo zenml_server.py (este es el archivo que se ejecutará cuando te conectes al servidor MCP). Este archivo está ubicado dentro de este repositorio en la raíz. Necesitarás especificar la ruta completa exacta a este archivo.
• la URL del servidor ZenML (esta es la URL de tu servidor ZenML. Puedes encontrarla en la interfaz de ZenML Cloud). Se verá algo como https://d534d987a-zenml.cloudinfra.zenml.io.
• la clave API del servidor ZenML (esta es la clave API para tu servidor ZenML. Puedes encontrarla en la interfaz de ZenML Cloud o lee estos documentos sobre cómo crear una. Para los propósitos del servidor MCP de ZenML recomendamos usar una cuenta de servicio).

Eres libre de cambiar la forma en que ejecutas el archivo Python del servidor MCP, pero usar uv será probablemente la opción más fácil ya que maneja el entorno y la instalación de dependencias por ti.

Instalación para uso con Claude Desktop

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

Necesitarás tener la última versión de Claude Desktop instalada.

Puedes simplemente abrir el menú de Configuración y arrastrar el archivo mcp-zenml.mcpb desde la raíz de este repositorio al menú y te guiará a través del proceso de instalación y configuración. Necesitarás agregar tu URL del servidor ZenML y clave API.

Nota: Los paquetes MCP (.mcpb) reemplazan el formato anterior de Extensiones de Escritorio (.dxt); los archivos .dxt existentes aún funcionan en Claude Desktop.

Opcional: Mejorar la Visualización de Salida de Herramientas de ZenML

Para una mejor experiencia con los resultados de las herramientas de ZenML, puedes configurar Claude para mostrar las respuestas JSON en un formato más legible. En Claude Desktop, ve a Configuración → Perfil, y en la sección "¿Qué preferencias personales debería considerar Claude en las respuestas?", agrega 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 formatear las salidas de las herramientas de ZenML como tablas de markdown, haciendo que la información sea mucho más fácil de leer y entender.

Instalación para uso con Cursor

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

Necesitarás tener Cursor instalado.

Cursor funciona de manera ligeramente diferente a Claude Desktop en que especificas el archivo de configuración por repositorio. Esto significa que si quieres usar el servidor MCP de ZenML en múltiples repos, necesitarás especificar el archivo de configuración en cada uno de ellos.

Para configurarlo para un solo repositorio, necesitarás:

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

En nuestra experiencia, a veces muestra un indicador de error rojo aunque esté funcionando. Puedes probarlo chateando en la ventana de chat de Cursor. Te hará saber si puede acceder a las herramientas de ZenML o no.

Imagen Docker

Puedes ejecutar el servidor como un contenedor Docker. El proceso se comunica a través de stdio, por lo que esperará una conexión de cliente MCP. Pasa tus credenciales de ZenML mediante variables de entorno.

Imágenes Precompiladas (Docker Hub)

Extrae la última imagen multi-arquitectura:

docker pull zenmldocker/mcp-zenml:latest

Las versiones con etiqueta se etiquetan como X.Y.Z:

docker pull zenmldocker/mcp-zenml:2.0.0

Ejecuta 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 MCP canónica usando 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) — el sucesor de las Extensiones de Escritorio (DXT) de Anthropic. Los Paquetes MCP empaquetan un servidor MCP completo (incluidas las dependencias) en un solo archivo con configuración fácil de usar.

Nota sobre el cambio de nombre: Los Paquetes MCP reemplazan el formato anterior .dxt. Claude Desktop sigue siendo compatible con versiones anteriores de archivos .dxt existentes, pero ahora enviamos mcp-zenml.mcpb y recomendamos usarlo en el futuro.

El archivo mcp-zenml.mcpb en la raíz del repositorio usa el runtime UV 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 incrustar extensiones nativas específicas de plataforma. La instalación necesita acceso a la red la primera vez que UV resuelve el entorno empaquetado.

Las compilaciones de paquetes reutilizan el mcpb-uv.lock confirmado y resuelven su gráfico 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 mientras mantienes cada pin que aún encaje; MCPB_REFRESH_LOCK=upgrade mueve cada pin a su versión más nueva. Cuando arrastras y sueltas el archivo .mcpb en la configuración de Claude Desktop, este maneja automáticamente:

• Instalación de dependencias en tiempo de ejecución
• Gestión segura de configuración
• Compatibilidad multiplataforma
• Proceso de configuración fácil de usar

Para más información, consulta el anuncio de Anthropic sobre las Extensiones de Escritorio (DXT) y la guía relacionada de empaquetado de paquetes MCP en su documentación: https://www.anthropic.com/engineering/desktop-extensions

Publicado en el Registro MCP de Anthropic

Este servidor MCP está publicado en el Registro MCP oficial de Anthropic y es detectable por hosts compatibles. En cada lanzamiento etiquetado, nuestro CI actualiza la entrada del registro mediante la CLI mcp-publisher del registro usando GitHub OIDC, por lo que puedes instalar o descubrir el Servidor MCP de ZenML directamente dondequiera que el registro sea compatible (por ejemplo, el catálogo de Extensiones de Claude Desktop).

• Siempre actualizado: la entrada del registro se actualiza con cada lanzamiento desde el manifest.json y server.json del commit etiquetado.
• Rutas de instalación alternativas: aún puedes instalar localmente mediante el paquete .mcpb (ver arriba) o ejecutar la imagen de Docker.

Aprende más sobre el registro aquí:

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