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 aplicações fornecem contexto para Modelos de Linguagem de Grande Porte (LLMs). Ele funciona como uma "porta USB-C para aplicações de IA" — fornecendo uma forma padronizada de conectar modelos de IA a diferentes fontes de dados e ferramentas.

O MCP segue uma arquitetura cliente-servidor onde:

• Hosts MCP: Programas como Claude Desktop ou IDEs que desejam acessar dados por meio do MCP
• Clientes MCP: Clientes de protocolo que mantêm conexões 1:1 com servidores
• Servidores MCP: Programas leves que expõem capacidades específicas 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 construir e gerenciar pipelines de ML e IA. Ela fornece uma interface unificada para gerenciar dados, modelos e experimentos.

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

Recursos

O servidor fornece ferramentas MCP para acessar funcionalidades principais de leitura do servidor ZenML, oferecendo uma forma de obter informações em tempo real 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 do stack
• Flavors — tipos de componentes disponíveis
• Conectores de Serviço — autenticação em nuvem

Execução de Pipelines

• Pipelines — definições de pipelines
• Execuções de Pipelines — histórico de execução e status
• Etapas de Pipelines — detalhes de etapas individuais, código e logs
• Agendamentos — agendamentos automáticos de execução
• Artefatos — metadados sobre artefatos de dados (não os dados em si)

Implantação e Serviço

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

Organização e Descoberta

• Projetos — contêineres organizacionais para recursos 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 Modelos — artefatos de modelo versionados

APIs de Compatibilidade (migração recomendada)

• Modelos de execução de pipeline permanecem 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 disparar novas execuções de pipeline usando snapshots (preferido) ou o parâmetro de disparo baseado em modelo, que está obsoleto.

Nota: Estamos continuamente melhorando esta integração com base no feedback dos usuários. Junte-se à nossa comunidade no Slack para compartilhar sua experiência e nos ajudar a torná-la ainda melhor!

Perfis de ferramentas e política de escrita

O perfil padrão compact anuncia 16 ferramentas. Sete ferramentas genéricas cobrem 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 suportados 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 suportado a partir de uma carga útil tipada
zenml_update_resource	Atualizar um UUID de recurso exato
zenml_delete_resource	Excluir ou arquivar um UUID de recurso exato
zenml_action_resource	Executar uma ação de ciclo de vida ou relação na lista de permissões sem tentativas

Nove ferramentas focadas permanecem porque fornecem diagnósticos, contexto ativo, logs ou código em fluxo contínuo, execução de pipelines ou um aplicativo 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, das mais antigas para as mais recentes, com um sinalizador possibly_truncated, além de um note informando quais entradas estão ausentes e o motivo. Passe tail para obter apenas as entradas mais recentes. Em servidores ZenML 0.97+, ele percorre o armazenamento de logs; no 0.96, usa o endpoint mais 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 ZenML 0.97.0. Ela não adiciona suporte para versões mais antigas do servidor ZenML. Use-a apenas durante a migração: as formas de resposta legadas podem expor mais metadados operacionais do que as ferramentas compactas, embora o servidor omita configurações com credenciais e outros campos sensíveis em ambos os perfis.

Registro e acesso de escrita 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 todas as quatro ferramentas genéricas de mutação e trigger_pipeline da descoberta e despacho do MCP. A descoberta de recursos também omite esquemas de criação, atualização, exclusão e ação. A configuração mais antiga ZENML_MCP_READ_ONLY=true permanece aceita; valores de política inválidos falham fechados no modo somente leitura. Um ZENML_MCP_PROFILE inválido interrompe a inicialização com um erro de configuração.

A versão 2.0.0 requer o SDK Python MCP 2.2.0 e ZenML 0.96.4. O perfil compacto é o novo padrão e é uma mudança de descoberta significativa 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, mova cada chamada para as ferramentas genéricas de recursos.

Os resultados de mutação distinguem resultados de 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 uma estiver disponível. A criação de webhooks e a rotação de segredos podem retornar um novo segredo de assinatura uma vez; leituras posteriores o omitem. Os esquemas de exclusão indicam se uma operação arquiva metadados, remove metadados, desprovisiona um recurso ativo ou pode excluir dados de artefatos armazenados.

O primeiro lançamento 2.0 cobre 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 leitura mostrada por zenml_describe_resources. Ele exclui a administração do plano de controle do ZenML Cloud, administração do Resource Manager, administração de usuários e credenciais, CRUD de valores de segredos, login e verificação de conectores, eventos brutos de webhook e ferramentas agregadas de depuração ou linhagem.

Inicie um fluxo de trabalho genérico descobrindo o esquema preciso 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 permanecem 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 do MCP, em vez de ferramentas.

Compatibilidade de 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 disparo baseado em modelo estão obsoletos. No perfil legado, get_run_template e list_run_templates permanecem disponíveis para clientes existentes.

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

Migração: Modelos de Execução → Snapshots

Por que a mudança? Os snapshots substituíram os modelos de execução como o artefato de pipeline executável preferido do ZenML. O SDK 0.97.0 ainda suporta CRUD de modelos de execução, enquanto o novo código 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 (Snapshot-Primeiro)

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 retorna saída limitada (padrão de 100 linhas, máximo de 1000, limitada a 100KB) e requer que a integração apropriada do implantador esteja instalada.

Configuração Rápida via Painel (Recomendado)

A maneira mais fácil de configurar o Servidor MCP do ZenML é pela página Configurações de MCP do seu painel ZenML.

Navegue até Configurações → MCP no seu painel ZenML para obter:

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

Usuários do ZenML Pro

A página Configurações de MCP permite gerar um Token de Acesso Pessoal (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 Configurações de MCP
3. Copie a configuração gerada para sua IDE

---

Prefere configuração manual? Consulte as instruções detalhadas abaixo.

Aplicativos MCP (Experimentais)

O que são Aplicativos MCP? Aplicativos MCP são UIs HTML interativas que os servidores MCP podem servir diretamente em clientes de IA. Eles são renderizados em iframes isolados e podem chamar ferramentas do servidor bidirecionalmente. Consulte o anúncio oficial para detalhes completos.

Este servidor inclui dois Aplicativos MCP experimentais:

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

Esses aplicativos são incluídos como exemplos de prova de conceito. Agradecemos feedback e contribuições para mais Aplicativos MCP. Ainda é cedo para esse novo recurso, então teremos que ver como ele evolui. Esperamos oferecer suporte mais completo no futuro.

Clientes Suportados

Os Aplicativos MCP exigem transporte HTTP Streamable (não stdio). Os seguintes clientes atualmente suportam Aplicativos MCP:

• ✅ VS Code (Edição Insiders)
• ✅ Goose
• ✅ ChatGPT (lançamento em breve)
• ⚠️ Claude Desktop — a partir do final de janeiro de 2026, ainda não renderiza Aplicativos.
• ⚠️ Claude.ai (web) — a partir do final de janeiro de 2026, ainda não renderiza Aplicativos.

Nota: Não foi possível testar completamente com Claude Desktop ou Claude.ai no momento da escrita. Se você encontrar problemas, relate-os.

Executando Aplicativos MCP com Docker

Os Aplicativos MCP usam HTTP Streamable. 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 na frente dele antes de permitir acesso remoto. A validação de Host e Origin protege contra rebinding de DNS; ela não autentica 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, 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 identidade ou credencial de serviço para o hostname público, e passe apenas requisições autenticadas para a origem. Configure seu cliente MCP para usar o fluxo OAuth suportado pelo provedor ou cabeçalhos de autorização.

Antes de adicionar credenciais do ZenML ao contêiner, verifique se uma requisição não autenticada não consegue alcançar o MCP:

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

A resposta deve ser o 401, 403 do provedor de acesso, ou um redirecionamento de login. Uma resposta JSON-RPC ou MCP significa que o perímetro está aberto e deve 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 de execuções"

Notas importantes:

• ZENML_ACTIVE_PROJECT_ID é obrigatório — sem ele, as ferramentas de execução de pipeline falharão com "Nenhum projeto está definido como ativo no momento"
• --disable-dns-rebinding-protection só é apropriado quando o proxy autenticado valida o host público e a porta do contêiner permanece apenas em loopback
• Restrinja a chave de API do ZenML às permissões que o cliente MCP precisa; use ZENML_MCP_WRITE_POLICY=read_only para clientes somente de inspeção

Testes e Garantia de Qualidade

Este projeto inclui testes automatizados para garantir que o servidor MCP permaneça funcional:

• 🔄 Testes de Fumaça Automatizados: Um teste de fumaça abrangente é executado a cada 3 dias via GitHub Actions
• 🚨 Criação de Issues: Testes com falha criam automaticamente issues no GitHub com informações detalhadas de depuração
• ⚡ CI Rápido: Usa UV com cache para instalação rápida de dependências e testes
• 🧪 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

CI sem credenciais cobre todos os adaptadores através do protocolo MCP. 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 CRUD persistido e recibos de isolamento de projeto com o mesmo nome. O servidor usa uma configuração temporária e um banco de dados que são removidos quando o job termina; nenhum ambiente de repositório, runner auto-hospedado ou credencial ZenML é necessário.

O servidor OSS local do ZenML desativa a autenticação e seu armazenamento SQL não suporta replay de pipeline ou infraestrutura de implantação externa. Acesso restrito e gatilhos habilitados por recursos, replay, implantação, condições de espera e recibos de solicitação de recursos permanecem, portanto, como portões 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 de fixtures descartáveis em ZENML_MCP_ACTION_FIXTURE, respectivamente. Um pulo com portão não é evidência de que essas capacidades passaram. Um operador pode definir ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 para transformar um portão opcional ausente em uma falha. O provisionamento de infraestrutura em nuvem nunca faz parte da execução de teste 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 pré-preenchidas — basta clicar em Conectar e usar a aba Ferramentas para testar qualquer ferramenta interativamente.

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

Privacidade e Analytics

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

Rastreamos:

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

NÃO coletamos:

• Sua URL do servidor ZenML ou chave de API
• Nomes de pipelines, nomes de modelos ou qualquer dado de negócio
• Mensagens de erro ou stack traces
• Qualquer informação pessoalmente identificável

Para desativar o analytics:

# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false

# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true

Para depuração/testes (registra eventos no stderr em vez de enviar):

export ZENML_MCP_ANALYTICS_DEV=true

Para usuários de 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 de ID do analytics, o servidor recorre a um UUID anônimo determinístico derivado de um hash de ZENML_STORE_URL (a URL em si nunca é enviada como uma propriedade de evento).

Opções adicionais de analytics:

• ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S — tempo máximo (em segundos) para enviar analytics de forma síncrona durante o desligamento (padrão: 1.0)

Nota sobre rastreamento de desligamento: Eventos de desligamento são enviados de forma síncrona com um timeout limitado para melhor confiabilidade de entrega. No entanto, se um contêiner for morto com SIGKILL (por exemplo, docker kill), os manipuladores de desligamento não podem ser acionados — isso é uma limitação do Docker/SO, não um bug.

Validação de Inicialização

Você pode habilitar 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 via variável de ambiente: ZENML_MCP_STARTUP_VALIDATION=warn.

A ferramenta diagnose_zenml_setup também está disponível como uma 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 as variáveis de ambiente estão ausentes.

Configuração Manual

Pré-requisitos

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

Dica: Assim que você tiver um servidor ZenML, confira a página de Configurações MCP no seu painel para a experiência de configuração mais fácil.

Compatibilidade: A versão atual é testada contra ZenML 0.97.0. Se você estiver executando uma versão mais antiga do ZenML, use uma versão anterior deste servidor MCP.

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

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

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

Seu arquivo de configuração MCP

O arquivo de configuração MCP é um arquivo JSON que informa ao cliente MCP como conectar-se ao seu servidor MCP. Diferentes clientes MCP usarão ou especificarão isso de maneiras diferentes. Dois clientes MCP comumente usados são Claude Desktop e Cursor, para os quais fornecemos instruções de instalação abaixo.

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

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

• o caminho para o seu uv instalado localmente (o caminho listado acima é onde ele estaria em um Mac se você o instalou via brew)
• o caminho para o arquivo zenml_server.py (este é o arquivo que será executado quando você se conectar ao servidor MCP). Este arquivo está localizado dentro deste repositório na raiz. Você precisará especificar o caminho completo exato para este arquivo.
• a URL do servidor ZenML (esta é a URL do seu servidor ZenML. Você pode encontrá-la na interface do ZenML Cloud). Ela será algo como https://d534d987a-zenml.cloudinfra.zenml.io.
• a chave de API do servidor ZenML (esta é a chave de API para o seu servidor ZenML. Você pode encontrá-la na interface do ZenML Cloud ou leia estes documentos sobre como criar uma. Para os propósitos do servidor MCP ZenML, recomendamos usar uma conta de serviço.)

Você é livre para mudar a forma como executa o arquivo Python do servidor MCP, mas usar uv provavelmente será a opção mais fácil, pois ele lida com o ambiente e a instalação de dependências para você.

Instalação para uso com Claude Desktop

Alternativa rápida: Use a página de Configurações MCP no seu painel ZenML (Configurações → MCP) para obter instruções de instalação pré-configuradas e deep links para Claude Desktop.

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

Você pode simplesmente abrir o menu Configurações e arrastar o arquivo mcp-zenml.mcpb da raiz deste repositório para o menu, e ele o guiará pelo processo de instalação e configuração. Você precisará adicionar sua URL do servidor ZenML e chave de API.

Nota: Os bundles MCP (.mcpb) substituem o formato mais antigo de Extensões de Desktop (.dxt); arquivos .dxt existentes ainda funcionam no Claude Desktop.

Opcional: Melhorando a Exibição da Saída das Ferramentas ZenML

Para uma melhor experiência com os resultados das ferramentas ZenML, você pode configurar o Claude para exibir as respostas JSON em um formato mais legível. No Claude Desktop, vá para Configurações → Perfil, e na seção "Quais preferências pessoais o Claude deve considerar nas respostas?", adicione algo como o seguinte (ou use estas palavras exatas!):

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 ZenML como tabelas markdown, tornando as informações muito mais fáceis de ler e entender.

Instalação para uso com Cursor

Alternativa rápida: A página de Configurações MCP no seu painel ZenML (Configurações → MCP) pode gerar o conteúdo exato do mcp.json com suas credenciais pré-preenchidas.

Você precisará ter o Cursor instalado.

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

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

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

Em nossa experiência, às vezes ele mostra um indicador de erro vermelho mesmo quando está funcionando. Você pode testá-lo conversando na janela de chat do Cursor. Ele informará se consegue acessar as ferramentas ZenML ou não.

Imagem Docker

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

Imagens Pré-construídas (Docker Hub)

Puxe a imagem multi-arquitetura mais recente:

docker pull zenmldocker/mcp-zenml:latest

Versões com release são marcadas como X.Y.Z:

docker pull zenmldocker/mcp-zenml:2.0.0

Execute com suas credenciais 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 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"
      ]
    }
  }
}

Construir Localmente

A partir da raiz do repositório:

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

Execute a imagem construída 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

Bundles MCP (.mcpb)

Este projeto usa Bundles MCP (.mcpb) — o sucessor das Extensões de Desktop (DXT) da Anthropic. Os Bundles MCP empacotam um servidor MCP inteiro (incluindo dependências) em um único arquivo com configuração amigável ao usuário.

Nota sobre renomeação: Os Bundles MCP substituem o formato mais antigo .dxt. O Claude Desktop permanece compatível com versões anteriores de arquivos .dxt existentes, mas agora enviamos mcp-zenml.mcpb e recomendamos usá-lo daqui em diante.

O arquivo mcp-zenml.mcpb na raiz do repositório usa o runtime UV MCPB 0.4. O host instala as dependências Python fixadas para o sistema operacional atual, então o mesmo bundle funciona em macOS, Windows e Linux sem incorporar extensões nativas específicas de plataforma. A instalação precisa de acesso à rede na primeira vez que o UV resolve o ambiente empacotado.

As construções de bundle reutilizam o mcpb-uv.lock commitado e resolvem seu grafo de dependências Python em modo offline. A lista de dependências do bundle vem de [project].dependencies em pyproject.toml. Após alterar essa lista, defina MCPB_REFRESH_LOCK=1 para re-resolver online, mantendo cada pin que ainda se encaixa; MCPB_REFRESH_LOCK=upgrade move cada pin para sua versão mais recente. Quando você arrasta e solta o arquivo .mcpb nas configurações do Claude Desktop, ele lida automaticamente com:

• Instalação de dependências em tempo de execução
• Gerenciamento seguro de configuração
• Compatibilidade entre plataformas
• Processo de configuração amigável ao usuário

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

Publicado no Registro MCP da Anthropic

Este servidor MCP está publicado no Registro MCP oficial da Anthropic e é detectável por hosts compatíveis. Em cada lançamento com tag, nossa CI atualiza a entrada do registro por meio da CLI mcp-publisher do registro usando GitHub OIDC, para que você possa instalar ou descobrir o Servidor MCP ZenML diretamente onde o registro for suportado (por exemplo, no catálogo de Extensões do Claude Desktop).

• Sempre atualizado: a entrada do registro é atualizada a cada lançamento a partir do manifest.json e server.json do commit com tag.
• Caminhos de instalação alternativos: você ainda pode instalar localmente por meio do bundle .mcpb empacotado (veja acima) ou executar a imagem Docker.

Saiba mais sobre o registro aqui:

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