ZenML

官方

通过你的 ZenML MCP 服务器与 MLOps 和 LLMOps 管道进行交互

GitHub

你可以用 ZenML MCP 做什么？

列出并检查管道运行 — 使用 list_pipeline_runs 和 get_run_step 检索执行历史、状态和步骤级详细信息。
触发新的管道运行 — 使用 trigger_pipeline 从冻结的快照配置启动运行。
检查部署状态和日志 — 通过 list_deployments 查找正在运行的部署，并使用 get_deployment_logs 获取绑定的日志。
探索堆栈和组件 — 使用 list_stacks 和 list_stack_components 列出基础设施配置及其构建块。
浏览模型注册表 — 使用 list_models 和 list_model_versions 发现已注册的模型及其版本化工件。
诊断连接问题 — 运行 diagnose_zenml_setup 以验证服务器URL、凭据和SDK连接性，即使在配置错误的情况下。

文档

ZenML 的 MCP 服务器

本项目实现了一个https://modelcontextprotocol.io/introduction 服务器，用于与 ZenML API 交互。

ZenML MCP Server

什么是 MCP？

模型上下文协议 (MCP) 是一种开放协议，标准化了应用程序向大语言模型 (LLM) 提供上下文的方式。它就像“AI 应用程序的 USB-C 端口”——提供了一种标准化的方式，将 AI 模型连接到不同的数据源和工具。

MCP 遵循客户端-服务器架构，其中：

MCP 主机：希望通过 MCP 访问数据的程序，如 Claude Desktop 或 IDE
MCP 客户端：与服务器保持 1:1 连接的协议客户端
MCP 服务器：通过标准化协议公开特定功能的轻量级程序
本地数据源：MCP 服务器可以安全访问的计算机文件、数据库和服务
远程服务：MCP 服务器可以连接的互联网上的外部系统

什么是 ZenML？

ZenML 是一个用于构建和管理 ML 及 AI 管道的开源平台。它提供了一个统一的界面来管理数据、模型和实验。

有关更多信息，请参阅 ZenML 网站和我们的文档。

功能

该服务器提供 MCP 工具来访问 ZenML 服务器的核心读取功能，从而能够获取以下方面的实时信息：

核心实体

用户 - 用户账户和权限
堆栈 - 基础设施配置
堆栈组件 - 单个堆栈构建块
类型 - 可用的组件类型
服务连接器 - 云身份验证

管道执行

管道 - 管道定义
管道运行 - 执行历史和状态
管道步骤 - 单个步骤的详细信息、代码和日志
计划 - 自动运行计划
工件 - 关于数据工件的元数据（而非数据本身）

部署与服务

快照 - 冻结的管道配置（“运行/服务什么”的工件）
部署 - 运行时服务实例，包含状态、URL 和日志
服务 - 模型服务端点

组织与发现

项目 - ZenML 资源的组织容器
标签 - 用于发现的跨领域元数据标签
构建 - 包含镜像和代码信息的管道构建工件

模型

模型 - ML 模型注册表条目
模型版本 - 版本化的模型工件

已弃用（建议迁移）

~~管道运行模板~~ → 改用快照（请参阅迁移指南）

该服务器还允许您使用快照（首选）或运行模板（已弃用）触发新的管道运行。

注意：我们正在根据用户反馈不断改进此集成。请加入我们的 Slack 社区分享您的经验，帮助我们做得更好！

可用工具

MCP 服务器公开了以下工具，按类别分组：

管道执行（v1.2 新增）

工具	描述
`get_snapshot`	按名称/ID 获取冻结的管道配置
`list_snapshots`	使用过滤器列出快照（可运行、可部署、已部署、标签）
`get_deployment`	获取部署的运行时状态和 URL
`list_deployments`	使用过滤器列出部署（状态、管道、标签）
`get_deployment_logs`	从部署获取有界日志（默认 tail=100，最大 1000）
`trigger_pipeline`	触发管道运行（首选 `snapshot_name_or_id` 参数）

组织（v1.2 新增）

工具	描述
`get_active_project`	获取当前活动项目
`get_project`	按名称/ID 获取项目详细信息
`list_projects`	列出所有项目
`get_tag`	获取标签详细信息（独占、颜色）
`list_tags`	使用过滤器列出标签（resource_type）
`get_build`	获取构建详细信息（镜像、代码嵌入）
`list_builds`	使用过滤器列出构建（is_local、contains_code）

核心实体

工具	描述
`get_user`、`list_users`、`get_active_user`	用户管理
`get_stack`、`list_stacks`	堆栈配置
`get_stack_component`、`list_stack_components`	堆栈组件
`get_flavor`、`list_flavors`	组件类型
`get_service_connector`、`list_service_connectors`	云连接器
`get_pipeline_run`、`list_pipeline_runs`	管道运行
`get_run_step`、`list_run_steps`	步骤详细信息
`get_step_logs`、`get_step_code`	步骤日志和源代码
`list_pipelines`、`get_pipeline_details`	管道定义
`get_schedule`、`list_schedules`	计划
`list_artifacts`	工件元数据
`list_secrets`	密钥名称（非值）
`get_service`、`list_services`	模型服务
`get_model`、`list_models`	模型注册表
`get_model_version`、`list_model_versions`	模型版本

交互式应用（实验性）

工具	描述
`open_pipeline_run_dashboard`	打开交互式管道运行仪表板（MCP 应用）
`open_run_activity_chart`	打开 30 天运行活动条形图（MCP 应用）

分析工具

工具	描述
`stack_components_analysis`	分析堆栈组件使用情况
`recent_runs_analysis`	分析最近的管道运行
`most_recent_runs`	获取 N 个最近的运行

诊断

工具	描述
`diagnose_zenml_setup`	诊断服务器设置（环境变量、SDK、连接性、身份验证）。即使在配置错误时也能工作。

已弃用的工具

工具	替代品
`get_run_template`	改用 `get_snapshot`
`list_run_templates`	改用 `list_snapshots`
`trigger_pipeline(template_id=...)`	改用 `trigger_pipeline(snapshot_name_or_id=...)`

迁移：运行模板 → 快照

为什么要更改？ ZenML 发展了其“可运行管道工件”的概念。运行模板现在是已弃用的包装器，内部仅指向快照。新代码应直接使用快照。

快速迁移指南

旧模式（模板）	新模式（快照）
`list_run_templates()`	`list_snapshots(runnable=True, named_only=True)`
`get_run_template(name)`	`get_snapshot(name, include_config_schema=True)`
`trigger_pipeline(template_id=...)`	`trigger_pipeline(snapshot_name_or_id=...)`

示例工作流程（快照优先）

1. Discover project context:
   → get_active_project()

2. Find runnable snapshots:
   → list_snapshots(runnable=True, named_only=True)

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

4. Check deployments:
   → list_deployments(status="running")
   → get_deployment_logs(name_id_or_prefix="my-deployment", tail=100)

注意： get_deployment_logs 返回有界输出（默认 100 行，最大 1000 行，上限 100KB），并且需要安装相应的部署器集成。

通过仪表板快速设置（推荐）

设置 ZenML MCP 服务器的最简单方法是通过 ZenML 仪表板的 MCP 设置页面。

MCP Settings Page

在 ZenML 仪表板中导航到设置 → MCP 以获取：

针对您的特定服务器 URL 和凭据的预配置代码片段
通过受支持 IDE 的深层链接进行一键安装
适用于 VS Code、Claude Desktop、Cursor、Claude Code、OpenAI Codex 等的复制粘贴配置
根据您的偏好选择 Docker 和 uv 选项

ZenML Pro 用户

MCP 设置页面允许您一键生成个人访问令牌 (PAT)。该令牌会自动包含在所有生成的配置代码片段中。

ZenML OSS 用户

首先通过设置 → 服务账户创建服务账户令牌
将令牌粘贴到 MCP 设置页面
复制为您的 IDE 生成的配置

更喜欢手动设置？ 请参阅下面的详细说明。

MCP 应用（实验性）

什么是 MCP 应用？ MCP 应用是 MCP 服务器可以直接提供给 AI 客户端的交互式 HTML UI。它们在沙盒 iframe 中渲染，并可以双向调用服务器工具。有关完整详细信息，请参阅官方公告。

Run Activity Chart

此服务器包含两个实验性 MCP 应用：

应用	工具	描述
管道运行仪表板	`open_pipeline_run_dashboard`	最近管道运行的交互式表格，包含状态、步骤详细信息和日志
运行活动图表	`open_run_activity_chart`	过去 30 天内管道运行活动的条形图，包含状态细分

Pipeline Runs Dashboard

这些应用作为概念验证示例包含在内。我们欢迎对更多 MCP 应用的反馈和贡献。这项新功能仍处于早期阶段，因此我们必须观察其如何发展。我们期望在未来更全面地支持它。

支持的客户端

MCP 应用需要可流式传输的 HTTP 传输（而非 stdio）。以下客户端目前支持 MCP 应用：

✅ VS Code（Insiders 版）
✅ Goose
✅ ChatGPT（即将推出）
⚠️ Claude Desktop -- 截至 2026 年 1 月下旬，尚未渲染应用。
⚠️ Claude.ai（网页版）——截至 2026 年 1 月下旬，尚未渲染应用。

注意： 在撰写本文时，我们无法使用 Claude Desktop 或 Claude.ai 进行彻底测试。如果您遇到问题，请报告。

使用 Docker 运行 MCP 应用

MCP 应用需要可流式传输的 HTTP 传输和一个可公开访问的 URL（适用于像 Claude.ai 这样的云托管客户端）。最简单的设置使用 Docker + Cloudflare 隧道：

1. 构建并运行 Docker 容器：

docker build -t mcp-zenml:apps .

docker run --rm -d --name mcp-zenml-apps -p 8001:8001 \
  -e ZENML_STORE_URL="https://your-zenml-server.example.com" \
  -e ZENML_STORE_API_KEY="your-api-key" \
  -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. 启动 Cloudflare 隧道（适用于云客户端）：

npx cloudflared tunnel --url http://localhost:8001

这将打印一个公共 URL，例如 https://random-words.trycloudflare.com。

3. 连接您的客户端：

在 Claude Desktop 或其他客户端中，添加带有 URL 的 MCP 服务器： https://random-words.trycloudflare.com/mcp 例如：

{
	"servers": {
		"ZenML": {
			"url": "https://USE-YOUR-OWN-URL.trycloudflare.com/mcp",
			"type": "http"
		}
	},
	"inputs": []
}

要求 AI“打开管道运行仪表板”或“显示运行活动图表”

重要说明：

ZENML_ACTIVE_PROJECT_ID 是必需的——没有它，管道运行工具将失败，并显示“当前未设置活动项目”
在反向代理（cloudflared、ngrok）后运行时需要 --disable-dns-rebinding-protection 标志——当代理处理安全性时，这是安全的
隧道 URL 在每次重启时都会更改——相应地更新您的客户端集成

测试与质量保证

本项目包含自动化测试，以确保 MCP 服务器保持功能正常：

🔄 自动化冒烟测试：每 3 天通过 GitHub Actions 运行一次全面的冒烟测试
🚨 问题创建：失败的测试会自动创建包含详细调试信息的 GitHub 问题
⚡ 快速 CI：使用 UV 进行缓存，以实现快速的依赖项安装和测试
🧪 手动测试：您可以使用 uv run scripts/test_mcp_server.py server/zenml_server.py 在本地运行冒烟测试

自动化测试验证：

MCP 协议连接和握手
服务器初始化和工具发现
基本工具功能（当 ZenML 服务器可访问时）
资源和提示枚举
diagnose_zenml_setup 即使在受限环境中也能返回结构化诊断信息

使用 MCP Inspector 进行调试

对于交互式调试，请使用 MCP Inspector——一个基于 Web 的工具，可让您实时测试 MCP 工具：

# 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

这将打开一个预填了您凭据的 Web UI——只需点击连接，然后使用工具选项卡交互式地测试任何工具。

有关更详细的调试说明，请参阅 CLAUDE.md。

隐私与分析

ZenML MCP 服务器收集匿名使用分析数据，以帮助我们改进产品。

我们跟踪：

使用了哪些工具以及使用频率
错误率和类型（仅错误类型，不包含消息）
基本环境信息（操作系统、Python 版本，以及是否在 Docker/CI 中运行）
会话时长和工具使用模式

我们不收集：

您的 ZenML 服务器 URL 或 API 密钥
管道名称、模型名称或任何业务数据
错误消息或堆栈跟踪
任何个人身份信息

要禁用分析：

# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false

# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true

用于调试/测试（将事件记录到 stderr 而不是发送）：

export ZENML_MCP_ANALYTICS_DEV=true

针对 Docker 用户： 您可以设置 ZENML_MCP_ANALYTICS_ID（必须是一个有效的 UUID），以便在容器重启时保持一致的匿名 ID。如果您未设置该变量，且容器文件系统无法持久化分析 ID 文件，服务器将回退到一个确定性的匿名 UUID，该 UUID 派生自 ZENML_STORE_URL 的哈希值（URL 本身永远不会作为事件属性发送）。

其他分析选项：

ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S — 在关闭期间同步刷新分析数据的最大时间（秒）（默认值：1.0）

关于关闭追踪的说明： 关闭事件会以有界超时的方式同步发送，以获得最佳的投递可靠性。但是，如果容器被 SIGKILL 终止（例如，docker kill），关闭处理程序将无法触发——这是 Docker/操作系统的限制，而非程序错误。

启动验证

您可以启用一个轻量级的启动诊断检查：

# 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

您也可以通过环境变量进行设置：ZENML_MCP_STARTUP_VALIDATION=warn。

diagnose_zenml_setup 工具也可作为 MCP 工具用于运行时故障排除——即使未安装 ZenML SDK 或缺少环境变量，它也能正常工作。

手动设置

前提条件

您需要能够访问已部署的 ZenML 服务器。如果您没有，可以在 ZenML Pro 注册免费试用，我们将为您管理部署。

提示： 拥有 ZenML 服务器后，请查看仪表板中的 MCP 设置页面，获取最简单的设置体验。

兼容性： 此 MCP 服务器已通过测试，推荐用于 ZenML >= 0.93.0。如果您运行的是较旧的 ZenML 版本，请使用此 MCP 服务器的早期版本。

您（很可能）还需要在本地安装 uv。有关更多信息，请参阅 uv 文档。我们建议通过其安装脚本进行安装，或者如果您使用的是 Mac，则通过 brew 进行安装。（从技术上讲，您并非必须安装它，但它会使安装和设置变得简单。）

您还需要在本地克隆此仓库：

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

您的 MCP 配置文件

MCP 配置文件是一个 JSON 文件，用于告知 MCP 客户端如何连接到您的 MCP 服务器。不同的 MCP 客户端使用或指定此文件的方式不同。两个常用的 MCP 客户端是 Claude Desktop 和 Cursor，我们在下面提供了它们的安装说明。

您需要按以下格式指定您的 ZenML MCP 服务器：

{
    "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",
                "PYTHONUNBUFFERED": "1",
                "PYTHONIOENCODING": "UTF-8",
                "ZENML_STORE_URL": "https://your-zenml-server-goes-here.com",
                "ZENML_STORE_API_KEY": "your-api-key-here"
            }
        }
    }
}

您需要替换四个虚拟值：

本地安装的 uv 的路径（上面列出的路径是在 Mac 上通过 brew 安装时的位置）
zenml_server.py 文件的路径（这是您连接到 MCP 服务器时将运行的文件）。此文件位于此仓库的根目录中。您需要指定此文件的完整路径。
ZenML 服务器 URL（这是您的 ZenML 服务器的 URL。您可以在 ZenML Cloud UI 中找到它）。它看起来类似于 https://d534d987a-zenml.cloudinfra.zenml.io。
ZenML 服务器 API 密钥（这是您的 ZenML 服务器的 API 密钥。您可以在 ZenML Cloud UI 中找到它，或者阅读这些文档了解如何创建。对于 ZenML MCP 服务器，我们建议使用服务账户。）

您可以自由更改运行 MCP 服务器 Python 文件的方式，但使用 uv 可能是最简单的选择，因为它会处理环境和依赖项安装。

与 Claude Desktop 配合使用的安装

快速替代方案： 使用 ZenML 仪表板中的 MCP 设置页面（设置 → MCP）获取预配置的安装说明和 Claude Desktop 的深层链接。

您需要安装最新版本的 Claude Desktop。

您只需打开“设置”菜单，将 mcp-zenml.mcpb 文件从此仓库的根目录拖放到菜单上，它将引导您完成安装和设置过程。您需要添加您的 ZenML 服务器 URL 和 API 密钥。

注意：MCP 捆绑包（.mcpb）取代了旧的桌面扩展（.dxt）格式；现有的 .dxt 文件在 Claude Desktop 中仍然有效。

可选：改善 ZenML 工具输出显示

为了获得更好的 ZenML 工具结果体验，您可以配置 Claude 以更易读的格式显示 JSON 响应。在 Claude Desktop 中，转到设置 → 个人资料，在“Claude 在回复时应考虑哪些个人偏好？” 部分，添加类似以下内容（或使用这些确切的词语！）：

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!

这将鼓励 Claude 将 ZenML 工具输出格式化为 Markdown 表格，使信息更易于阅读和理解。

与 Cursor 配合使用的安装

快速替代方案： ZenML 仪表板中的 MCP 设置页面（设置 → MCP）可以生成精确的 mcp.json 内容，并预填您的凭据。

您需要安装 Cursor。

Cursor 的工作方式与 Claude Desktop 略有不同，您需要在每个仓库的基础上指定配置文件。这意味着，如果您想在多个仓库中使用 ZenML MCP 服务器，则需要在每个仓库中指定配置文件。

要为单个仓库进行设置，您需要：

在仓库的根目录中创建一个 .cursor 文件夹
在其中创建一个包含上述内容的 mcp.json 文件
进入您的 Cursor 设置，点击 ZenML 服务器以“启用”它。

根据我们的经验，有时即使它正在工作，也会显示红色错误指示器。您可以在 Cursor 聊天窗口中尝试一下。它会告知您是否能够访问 ZenML 工具。

Docker 镜像

您可以将服务器作为 Docker 容器运行。该进程通过 stdio 进行通信，因此它将等待 MCP 客户端连接。通过环境变量传递您的 ZenML 凭据。

预构建镜像（Docker Hub）

拉取最新的多架构镜像：

docker pull zenmldocker/mcp-zenml:latest

版本化发布标记为 X.Y.Z：

docker pull zenmldocker/mcp-zenml:1.0.8

使用您的 ZenML 凭据运行（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

使用 Docker 的规范 MCP 配置

{
  "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", "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"
      ]
    }
  }
}

本地构建

从仓库根目录：

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

运行本地构建的镜像：

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

MCP 捆绑包 (.mcpb)

此项目使用 MCP 捆绑包（.mcpb）——Anthropic 桌面扩展（DXT）的继任者。MCP 捆绑包将整个 MCP 服务器（包括依赖项）打包到一个文件中，并提供用户友好的配置。

关于重命名：MCP 捆绑包取代了旧的 .dxt 格式。Claude Desktop 保持对现有 .dxt 文件的向后兼容性，但我们现在提供 mcp-zenml.mcpb，并建议您今后使用它。

仓库根目录中的 mcp-zenml.mcpb 文件包含了运行 ZenML MCP 服务器所需的一切，无需复杂的手动安装步骤。这使得强大的 ZenML 集成可供用户使用，而无需技术设置专业知识。

当您将 .mcpb 文件拖放到 Claude Desktop 的设置中时，它会自动处理：

运行时依赖项安装
安全的配置管理
跨平台兼容性
用户友好的设置过程

有关更多信息，请参阅 Anthropic 在其文档中关于桌面扩展（DXT）的公告以及相关的 MCP 捆绑包打包指南：https://www.anthropic.com/engineering/desktop-extensions

已在 Anthropic MCP 注册表中发布

此 MCP 服务器已发布到官方的 Anthropic MCP 注册表，可被兼容的主机发现。在每次标记发布时，我们的 CI 会通过注册表的 mcp-publisher CLI 使用 GitHub OIDC 更新注册表条目，因此您可以在任何支持注册表的地方（例如，Claude Desktop 的扩展目录）直接安装或发现 ZenML MCP 服务器。

始终保持最新： 注册表条目会在每次发布时从标记提交的 manifest.json 和 server.json 进行刷新。
备用安装路径： 您仍然可以通过打包的 .mcpb 捆绑包进行本地安装（见上文），或运行 Docker 镜像。

在此处了解有关注册表的更多信息：

Anthropic MCP 注册表（社区仓库）：https://github.com/modelcontextprotocol/registry