ZenML

Servidor MCP para ZenML

Este projeto implementa um servidor Model Context Protocol (MCP) para interagir com a API do ZenML.

O que é MCP?

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como aplicativos fornecem contexto a Large Language Models (LLMs). Ele funciona como uma "porta USB-C para aplicativos de IA" — oferecendo uma maneira padronizada de conectar modelos de IA a diferentes fontes de dados e ferramentas.

O MCP segue uma arquitetura cliente-servidor, na qual:

• Hosts MCP: programas como Claude Desktop ou IDEs que querem acessar dados por meio do MCP
• Clientes MCP: clientes do protocolo que mantêm conexões 1:1 com servidores
• Servidores MCP: programas leves que expõem recursos específicos por meio do protocolo padronizado
• Fontes de dados locais: arquivos, bancos de dados e serviços do seu computador que os servidores MCP podem acessar com segurança
• Serviços remotos: sistemas externos disponíveis pela internet aos quais os servidores MCP podem se conectar

O que é ZenML?

ZenML é uma plataforma de código aberto para criar e gerenciar pipelines de ML e IA. Ela oferece uma interface unificada para gerenciar dados, modelos e experimentos.

Para mais informações, consulte o site do ZenML e nossa documentação.

Recursos

O servidor fornece ferramentas MCP para acessar funcionalidades essenciais de leitura do servidor ZenML, oferecendo uma maneira de obter informações atualizadas sobre:

Entidades principais

• Usuários - contas de usuário e permissões
• Stacks - configurações de infraestrutura
• Componentes de stack - blocos de construção individuais de uma stack
• Flavors - tipos de componentes disponíveis
• Conectores de serviço - autenticação na nuvem

Execução de pipelines

• Pipelines - definições de pipeline
• Execuções de pipeline - histórico e status de execução
• Etapas de pipeline - detalhes, código e logs de cada etapa
• Agendamentos - agendamentos de execução automatizados
• Artefatos - metadados sobre artefatos de dados (não os dados em si)

Implantação e serving

• Snapshots - configurações de pipeline congeladas (o artefato que define "o que executar/servir")
• Implantações - instâncias de serving em tempo de execução com status, URL e logs
• Serviços - endpoints de serving de modelos

Organização e descoberta

• Projetos - contêineres organizacionais para recursos do ZenML
• Tags - rótulos de metadados transversais para descoberta
• Builds - artefatos de build de pipeline com informações de imagem e código

Modelos

• Modelos - entradas do registro de modelos de ML
• Versões de modelo - artefatos de modelo com controle de versão

APIs de compatibilidade (recomenda-se a migração)

• Modelos de execução de pipeline continuam disponíveis no ZenML 0.97.0, enquanto Snapshots são preferidos para novos fluxos de trabalho (consulte o Guia de migração)

O servidor também permite acionar novas execuções de pipeline usando snapshots (preferencialmente) ou o parâmetro de acionamento baseado em modelos, que está obsoleto.

Observação: estamos aprimorando continuamente esta integração com base no feedback dos usuários. Participe da nossa comunidade no Slack para compartilhar sua experiência e nos ajudar a torná-la ainda melhor!

Perfis de ferramentas e política de gravação

O perfil padrão compact anuncia 16 ferramentas. Sete ferramentas genéricas abrangem o catálogo de recursos, leituras, mutações comuns e ações de ciclo de vida finitas:

Ferramenta	Finalidade
zenml_describe_resources	Descobrir tipos de recursos compatíveis e esquemas de operação limitados
zenml_list_resources	Listar um tipo de recurso com filtros validados e paginação
zenml_get_resource	Obter um recurso, com escopo de pai e projeto quando necessário
zenml_create_resource	Criar um recurso compatível a partir de um payload tipado
zenml_update_resource	Atualizar um UUID exato de recurso
zenml_delete_resource	Excluir ou arquivar um UUID exato de recurso
zenml_action_resource	Executar uma ação permitida de ciclo de vida ou relação sem novas tentativas

Nove ferramentas específicas continuam disponíveis porque fornecem diagnósticos, contexto ativo, logs ou código transmitidos em fluxo, execução de pipeline ou um App interativo:

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

get_step_logs retorna no máximo 50,000 entradas, da mais antiga para a mais recente, com uma flag possibly_truncated, além de um note que informa quais entradas estão ausentes e por quê. Passe tail para obter apenas as entradas mais recentes. Em servidores ZenML 0.97+, ele percorre as páginas do armazenamento de logs; na versão 0.96, usa o endpoint antigo de solicitação única.

Use ZENML_MCP_PROFILE=legacy quando um cliente existente ainda depender dos nomes antigos específicos de entidade, como list_pipeline_runs. Isso mantém a camada de compatibilidade de nomes de ferramentas e esquemas caracterizada para o ZenML 0.97.0. Não adiciona suporte a versões anteriores do servidor ZenML. Use-o apenas durante a migração: os formatos de resposta legados podem expor mais metadados operacionais do que as ferramentas compactas, embora o servidor omita configurações que contenham credenciais e outros campos confidenciais em ambos os perfis.

O registro e o acesso de gravação são independentes:

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

Defina ZENML_MCP_WRITE_POLICY=read_only para remover as quatro ferramentas genéricas de mutação e trigger_pipeline da descoberta e do despacho do MCP. A descoberta de recursos também omite os esquemas de criação, atualização, exclusão e ação. A configuração antiga ZENML_MCP_READ_ONLY=true continua sendo aceita; valores de política inválidos resultam em modo somente leitura. Um valor inválido de ZENML_MCP_PROFILE interrompe a inicialização com um erro de configuração.

A versão 2.0.0 requer MCP Python SDK 2.2.0 e ZenML 0.96.4. O perfil compacto é o novo padrão e representa uma alteração incompatível na descoberta para clientes que chamam nomes de ferramentas específicos de entidade. Defina ZENML_MCP_PROFILE=legacy durante a migração desses clientes e, em seguida, migre cada chamada para as ferramentas genéricas de recursos.

Os resultados de mutação distinguem os estados completed, accepted e unknown. O servidor não tenta novamente uma mutação depois que ela pode ter chegado ao ZenML. Para um resultado aceito ou desconhecido, siga as instruções de reconciliação na resposta antes de decidir se deve chamar novamente. Use a leitura nomeada quando disponível. A criação de webhook e a rotação de segredo podem retornar um novo segredo de assinatura uma única vez; leituras posteriores o omitem. Os esquemas de exclusão informam se uma operação arquiva metadados, remove metadados, desprovisiona um recurso ativo ou pode excluir dados de artefatos armazenados.

A primeira versão 2.0 abrange operações comuns para projetos, stacks e componentes, flavors, serviços, pipelines e execuções, snapshots e modelos, implantações, artefatos e versões, modelos e versões, tags, conectores, repositórios de código, webhooks, gatilhos, condições de espera e invocações de hooks. Usuários, agendamentos, tipos de conectores de serviço, segredos e solicitações de recursos têm a cobertura somente de leitura indicada por zenml_describe_resources. Ela exclui a administração do plano de controle do ZenML Cloud, a administração do Resource Manager, a administração de usuários e credenciais, operações CRUD de valores de segredos, login e verificação de conectores, eventos brutos de webhook e ferramentas agregadas de depuração ou linhagem.

Comece um fluxo de trabalho genérico descobrindo o esquema exato e, em seguida, chamando-o:

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,
)

Prompts e recursos continuam disponíveis em ambos os perfis. Os prompts de análise, os endpoints limitados de esquema de recursos e most_recent_runs são prompts ou recursos MCP, não ferramentas.

Compatibilidade com modelos de execução

O ZenML 0.97.0 mantém as APIs CRUD de modelos de execução. Snapshots são preferidos para novos fluxos de trabalho. A criação conveniente de pipelines e o parâmetro de acionamento baseado em modelos estão obsoletos. No perfil legado, get_run_template e list_run_templates continuam disponíveis para clientes existentes.

A entrada legada tag continua em list_run_templates para compatibilidade de esquema, mas o ZenML 0.97.0 não tem um filtro equivalente no servidor. Um valor não nulo é rejeitado antes da chamada ao SDK. A filtragem de tags de snapshot continua disponível.

Migração: modelos de execução → snapshots

Por que a mudança? Os snapshots substituíram os modelos de execução como artefato de pipeline executável preferido do ZenML. O SDK 0.97.0 ainda oferece suporte a operações CRUD de modelos de execução, enquanto o código novo deve usar snapshots.

Guia rápido de migração

Padrão legado (modelos)	Padrão 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=...)

Exemplo de fluxo de trabalho (priorizando 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 substituir parâmetros ao acionar um snapshot executável, passe uma configuração de execução do ZenML (o snapshot em si permanece inalterado):

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

Para snapshots estáticos, substitua os parâmetros das etapas conforme mostrado acima. As substituições de run_configuration={"parameters": {...}} no nível superior substituem os parâmetros da função do pipeline e são compatíveis apenas com snapshots dinâmicos; o ZenML as rejeita para snapshots estáticos.

Observação: get_deployment_logs retorna uma saída limitada (100 linhas por padrão, máximo de 1000, limitada a 100KB) e requer a instalação da integração de deployer apropriada.

Configuração rápida pelo Dashboard (recomendado)

A maneira mais fácil de configurar o servidor MCP do ZenML é pela página de configurações de MCP do seu dashboard do ZenML.

Acesse Configurações → MCP no dashboard do ZenML para obter:

• Trechos pré-configurados para a URL e as credenciais específicas do seu servidor
• Instalação com um clique por meio de links diretos para IDEs compatíveis
• Configurações para copiar e colar no VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex e outros
• Opções de Docker e uv de acordo com sua preferência

Usuários do ZenML Pro

A página de configurações de MCP permite gerar um Personal Access Token (PAT) com um único clique. O token é incluído automaticamente em todos os trechos de configuração gerados.

Usuários do ZenML OSS

1. Primeiro, crie um token de conta de serviço em Configurações → Contas de serviço
2. Cole o token na página de configurações de MCP
3. Copie a configuração gerada para sua IDE

---

Prefere configurar manualmente? Consulte as instruções detalhadas abaixo.

MCP Apps (experimental)

O que são MCP Apps? MCP Apps são interfaces HTML interativas que servidores MCP podem fornecer diretamente a clientes de IA. Elas são renderizadas em iframes isolados e podem chamar ferramentas do servidor nos dois sentidos. Consulte o anúncio oficial para obter todos os detalhes.

Este servidor inclui dois MCP Apps experimentais:

App	Ferramenta	Descrição
Painel de execuções de pipeline	open_pipeline_run_dashboard	Tabela interativa de execuções recentes de pipeline com status, detalhes das etapas e logs
Gráfico de atividade de execuções	open_run_activity_chart	Gráfico de barras da atividade de execução de pipelines nos últimos 30 dias, com detalhamento por status

Esses apps são incluídos como exemplos de prova de conceito. Agradecemos feedback e contribuições para mais MCP Apps. Ainda estamos no início dessa nova funcionalidade, então veremos como ela evolui. Esperamos oferecer suporte mais completo no futuro.

Clientes compatíveis

MCP Apps requerem transporte Streamable HTTP (não stdio). Os seguintes clientes atualmente oferecem suporte a MCP Apps:

• ✅ VS Code (edição Insiders)
• ✅ Goose
• ✅ ChatGPT (lançamento em breve)
• ⚠️ Claude Desktop — até o fim de janeiro de 2026, ainda não renderiza Apps.
• ⚠️ Claude.ai (web) — até o fim de janeiro de 2026, ainda não renderiza Apps.

Observação: não foi possível testar exaustivamente com Claude Desktop ou Claude.ai no momento da redação. Se encontrar problemas, relate-os.

Executar MCP Apps com Docker

MCP Apps usam Streamable HTTP. Mantenha a porta do contêiner vinculada ao loopback e coloque um proxy reverso autenticado ou um serviço de acesso com reconhecimento de identidade à frente dele antes de permitir acesso remoto. A validação de Host e Origin protege contra rebinding de DNS; ela não autentica os chamadores.

1. Crie e execute o contêiner 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. Configure o acesso remoto autenticado:

Crie um Cloudflare Tunnel nomeado, um Tailscale Funnel com controles de acesso ou um proxy reverso autenticado equivalente. Aponte sua origem privada para http://127.0.0.1:8001, exija uma credencial de identidade ou de serviço para o hostname público e encaminhe apenas solicitações autenticadas para a origem. Configure seu cliente MCP para usar o fluxo OAuth ou os cabeçalhos de autorização compatíveis com o provedor.

Antes de adicionar as credenciais do ZenML ao contêiner, verifique se uma solicitação não autenticada não consegue acessar o MCP:

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

A resposta deve ser o 401, o 403 ou um redirecionamento para login do provedor de acesso. Uma resposta JSON-RPC ou MCP significa que o perímetro está aberto e precisa ser corrigido primeiro.

3. Conecte seu cliente autenticado:

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

• Peça à IA para "abrir o painel de execuções de pipeline" ou "mostrar o gráfico de atividade das execuções"

Observações importantes:

• ZENML_ACTIVE_PROJECT_ID é obrigatório — sem ele, as ferramentas de execução de pipeline falharão com "No project is currently set as active"
• --disable-dns-rebinding-protection só é apropriado quando o proxy autenticado valida o host público e a porta do contêiner permanece acessível apenas por loopback
• Restrinja a chave de API do ZenML às permissões necessárias para o cliente MCP; use ZENML_MCP_WRITE_POLICY=read_only para clientes que só precisam inspecionar

Testes e garantia de qualidade

Este projeto inclui testes automatizados para garantir que o servidor MCP continue funcionando:

• 🔄 Testes automatizados de fumaça: um teste de fumaça abrangente é executado a cada 3 dias pelo GitHub Actions
• 🚨 Criação de issues: testes com falha criam automaticamente issues no GitHub com informações detalhadas para depuração
• ⚡ CI rápido: usa UV com cache para instalar dependências e executar testes rapidamente
• 🧪 Testes manuais: você pode executar o teste de fumaça localmente usando uv run scripts/test_mcp_server.py server/zenml_server.py

Os testes automatizados verificam:

• Conexão e handshake do protocolo MCP
• Inicialização do servidor e descoberta de ferramentas
• Funcionalidade básica das ferramentas (quando o servidor ZenML está acessível)
• Enumeração de recursos e prompts
• diagnose_zenml_setup retorna diagnósticos estruturados mesmo em ambientes restritos

O CI sem credenciais cobre todos os adaptadores pelo protocolo MCP. O CI de PR e de release também inicia um servidor OSS ZenML 0.97.0 novo em um endereço de loopback e executa comprovantes de CRUD persistente e de isolamento de projetos com o mesmo nome. O servidor usa uma configuração e um banco de dados temporários, removidos quando o job termina; não é necessário ambiente do repositório, runner auto-hospedado nem credencial do ZenML.

O servidor OSS local do ZenML desativa a autenticação, e seu armazenamento SQL não oferece suporte à repetição de pipelines nem à infraestrutura de implantação externa. Os comprovantes de acesso restrito e de gatilhos, repetição, implantação, condições de espera e solicitações de recursos com recursos habilitados permanecem, portanto, como gates opcionais separados. Eles exigem ZENML_MCP_RESTRICTED_INTEGRATION=1 com ZENML_MCP_RESTRICTED_API_KEY, ou ZENML_MCP_ACTION_INTEGRATION=1 com os UUIDs exatos das fixtures descartáveis em ZENML_MCP_ACTION_FIXTURE, respectivamente. Um skip por gate não comprova que esses recursos passaram. Um operador pode definir ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 para transformar a ausência de um gate opcional em falha. O provisionamento de infraestrutura em nuvem nunca faz parte da execução de testes padrão.

Depuração com o MCP Inspector

Para depuração interativa, use o MCP Inspector — uma ferramenta baseada na web que permite testar ferramentas MCP em tempo 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

Isso abre uma interface web com suas credenciais preenchidas — basta clicar em Connect e usar a aba Tools para testar qualquer ferramenta interativamente.

Consulte CLAUDE.md para instruções de depuração mais detalhadas.

Privacidade e análise de uso

O servidor MCP do ZenML coleta dados anônimos de uso para nos ajudar a melhorar o produto.

Coletamos:

• Quais ferramentas são usadas e com que frequência
• Taxas e tipos de erro (somente o tipo de erro, sem mensagens)
• Informações básicas do ambiente (SO, versão do Python e se está sendo executado no Docker/CI)
• Duração da sessão e padrões de uso das ferramentas

NÃO coletamos:

• A URL do seu servidor ZenML nem a chave de API
• Nomes de pipelines, nomes de modelos ou quaisquer dados comerciais
• Mensagens de erro ou rastreamentos de pilha
• Qualquer informação de identificação pessoal

Para desativar a análise de uso:

# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false

# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true

Para depuração/testes (registra eventos em stderr em vez de enviá-los):

export ZENML_MCP_ANALYTICS_DEV=true

Para usuários do Docker: você pode definir ZENML_MCP_ANALYTICS_ID (deve ser um UUID válido) para manter um ID anônimo consistente entre reinicializações do contêiner. Se você não o definir e o sistema de arquivos do contêiner não puder persistir o arquivo do ID de análise de uso, o servidor usará como alternativa um UUID anônimo determinístico derivado de um hash de ZENML_STORE_URL (a URL em si nunca é enviada como propriedade de evento).

Opções adicionais de análise de uso:

• ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S — tempo máximo (segundos) para enviar a análise de uso de forma síncrona durante o encerramento (padrão: 1.0)

Observação sobre o rastreamento do encerramento: os eventos de encerramento são enviados de forma síncrona, com um tempo limite limitado para aumentar a confiabilidade da entrega. No entanto, se um contêiner for encerrado com SIGKILL (por exemplo, docker kill), os manipuladores de encerramento não poderão ser executados — isso é uma limitação do Docker/SO, não um bug.

Validação na inicialização

Você pode ativar uma verificação de diagnóstico leve na inicialização:

# 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

Você também pode definir isso por meio da variável de ambiente: ZENML_MCP_STARTUP_VALIDATION=warn.

A ferramenta diagnose_zenml_setup também está disponível como ferramenta MCP para solução de problemas em tempo de execução — ela funciona mesmo quando o SDK do ZenML não está instalado ou quando faltam variáveis de ambiente.

Configuração manual

Pré-requisitos

Você precisará ter acesso a um servidor ZenML implantado. Se não tiver um, poderá se inscrever para uma avaliação gratuita no ZenML Pro, e nós gerenciaremos a implantação para você.

Dica: depois de ter um servidor ZenML, confira a página de configurações do MCP no seu painel para configurar tudo com mais facilidade.

Compatibilidade: a versão atual foi testada com o ZenML 0.97.0. Se você estiver usando uma versão mais antiga do ZenML, use uma versão anterior deste servidor MCP.

Você também provavelmente precisará ter uv instalado localmente. Para mais informações, consulte a documentação do uv. Recomendamos a instalação pelo script instalador ou por meio de brew se estiver usando um Mac. (Tecnicamente, você não precisa dele, mas ele facilita a instalação e a configuração.)

Você também precisará clonar este repositório em algum local:

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

Seu arquivo de configuração do MCP

O arquivo de configuração do MCP é um arquivo JSON que informa ao cliente MCP como se conectar ao seu servidor MCP. Clientes MCP diferentes usam ou especificam esse arquivo de maneiras diferentes. Dois clientes MCP bastante usados são o Claude Desktop e o Cursor, para os quais fornecemos instruções de instalação abaixo.

Você precisará especificar seu servidor MCP do ZenML no seguinte 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"
            }
        }
    }
}

Quando ZENML_STORE_API_KEY é fornecido, o servidor MCP mantém as credenciais do ZenML na memória e não lê nem atualiza as credenciais salvas por zenml login. Isso se aplica a execuções diretas do Python, extensões MCPB e Docker. Conexões sem uma chave de API ainda podem usar o login salvo no terminal. Reinicie o servidor MCP depois de alterar sua chave de API; um novo chat, por si só, pode reutilizar o processo do servidor em execução.

Há quatro valores fictícios que você precisará substituir:

• o caminho para a instalação local de uv (o caminho listado acima é onde ele ficaria em um Mac se você o instalasse por meio de brew)
• o caminho para o arquivo zenml_server.py (este é o arquivo que será executado quando você se conectar ao servidor MCP). Esse arquivo está na raiz deste repositório. Você precisará especificar o caminho completo exato para esse arquivo.
• a URL do servidor ZenML (esta é a URL do seu servidor ZenML. Você pode encontrá-la na interface do ZenML Cloud). Ela será parecida com https://d534d987a-zenml.cloudinfra.zenml.io.
• a chave de API do servidor ZenML (esta é a chave de API do seu servidor ZenML. Você pode encontrá-la na interface do ZenML Cloud ou consultar esta documentação para saber como criar uma. Para o servidor MCP do ZenML, recomendamos usar uma conta de serviço.)

Você pode alterar a forma de executar o arquivo Python do servidor MCP, mas usar uv provavelmente será a opção mais fácil, pois ele gerencia o ambiente e a instalação das dependências para você.

Instalação para uso com o Claude Desktop

Alternativa rápida: use a página de configurações do MCP no painel do ZenML (Settings → MCP) para obter instruções de instalação pré-configuradas e links diretos para o Claude Desktop.

Você precisará ter a versão mais recente do Claude Desktop instalada.

Basta abrir o menu Settings e arrastar o arquivo mcp-zenml.mcpb da raiz deste repositório para o menu. Ele guiará você pelo processo de instalação e configuração. Você precisará adicionar a URL e a chave de API do seu servidor ZenML.

Observação: os pacotes MCP (.mcpb) substituem o formato antigo de Desktop Extensions (.dxt); os arquivos .dxt existentes ainda funcionam no Claude Desktop.

Opcional: melhorar a exibição da saída das ferramentas do ZenML

Para ter uma experiência melhor com os resultados das ferramentas do ZenML, você pode configurar o Claude para exibir as respostas JSON em um formato mais legível. No Claude Desktop, acesse Settings → Profile e, na seção "What personal preferences should Claude consider in responses?", adicione algo como o seguinte (ou use exatamente estas palavras!):

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!

Isso incentivará o Claude a formatar as saídas das ferramentas do ZenML como tabelas Markdown, facilitando muito a leitura e a compreensão das informações.

Instalação para uso com o Cursor

Alternativa rápida: a página de configurações do MCP no painel do ZenML (Settings → MCP) pode gerar o conteúdo exato de mcp.json com suas credenciais preenchidas.

Você precisará ter o Cursor instalado.

O Cursor funciona de maneira um pouco diferente do Claude Desktop: nele, você especifica o arquivo de configuração por repositório. Isso significa que, se quiser usar o servidor MCP do ZenML em vários repositórios, precisará especificar o arquivo de configuração em cada um deles.

Para configurá-lo em um único repositório, você precisará:

• criar uma pasta .cursor na raiz do seu repositório
• criar dentro dela um arquivo mcp.json com o conteúdo acima
• acessar as configurações do Cursor e clicar no servidor ZenML para "ativá-lo".

Em nossa experiência, às vezes aparece um indicador de erro vermelho mesmo quando está funcionando. Você pode testar conversando na janela de chat do Cursor. Ele informará se consegue acessar as ferramentas do ZenML.

Imagem Docker

Você pode executar o servidor como um contêiner Docker. O processo se comunica por stdio, então aguardará uma conexão de cliente MCP. Passe suas credenciais do ZenML por meio de variáveis de ambiente.

Imagens pré-criadas (Docker Hub)

Baixe a imagem multi-arquitetura mais recente:

docker pull zenmldocker/mcp-zenml:latest

As versões lançadas são marcadas como X.Y.Z:

docker pull zenmldocker/mcp-zenml:2.0.0

Execute com suas credenciais do 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

Configuração canônica do MCP 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

Na raiz do repositório:

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

Execute a imagem 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

Pacotes MCP (.mcpb)

Este projeto usa pacotes MCP (.mcpb) — os sucessores das Desktop Extensions (DXT) da Anthropic. Os pacotes MCP reúnem um servidor MCP completo (incluindo dependências) em um único arquivo com configuração fácil de usar.

Observação sobre a mudança de nome: os pacotes MCP substituem o formato antigo .dxt. O Claude Desktop continua compatível com os arquivos .dxt existentes, mas agora distribuímos mcp-zenml.mcpb e recomendamos seu uso daqui em diante.

O arquivo mcp-zenml.mcpb na raiz do repositório usa o runtime UV do MCPB 0.4. O host instala as dependências Python fixadas para o sistema operacional atual, portanto, o mesmo pacote funciona no macOS, Windows e Linux sem incorporar extensões nativas específicas da plataforma. A instalação precisa de acesso à rede na primeira vez que o UV resolve o ambiente incluído. As compilações do bundle reutilizam o mcpb-uv.lock confirmado no repositório e resolvem o grafo de dependências do Python no modo offline. A lista de dependências do bundle vem de [project].dependencies em pyproject.toml. Depois de alterar essa lista, defina MCPB_REFRESH_LOCK=1 para resolver novamente online, mantendo cada versão fixada que ainda seja compatível; MCPB_REFRESH_LOCK=upgrade atualiza todas as versões fixadas para as mais recentes.

Ao arrastar e soltar o arquivo .mcpb nas configurações do Claude Desktop, ele gerencia automaticamente:

• Instalação de dependências de runtime
• Gerenciamento seguro da configuração
• Compatibilidade entre plataformas
• Processo de configuração fácil de usar

Para mais informações, consulte o anúncio da Anthropic sobre as Desktop Extensions (DXT) e as orientações relacionadas ao empacotamento de bundles MCP na documentação: https://www.anthropic.com/engineering/desktop-extensions

Publicado no Anthropic MCP Registry

Este servidor MCP está publicado no Anthropic MCP Registry oficial e pode ser descoberto por hosts compatíveis. A cada versão marcada, nosso CI atualiza a entrada no registro por meio da CLI mcp-publisher do registro, usando GitHub OIDC, para que você possa instalar ou descobrir o ZenML MCP Server diretamente onde o registro for compatível (por exemplo, no catálogo de extensões do Claude Desktop).

• Sempre atualizado: a entrada no registro é atualizada a cada versão com base no manifest.json e no server.json do commit marcado.
• Caminhos alternativos de instalação: você ainda pode instalar localmente usando o bundle .mcpb empacotado (veja acima) ou executar a imagem Docker.

Saiba mais sobre o registro aqui:

• Anthropic MCP Registry (repositório da comunidade): https://github.com/modelcontextprotocol/registry