ZenML MCP Server

ZenML的MCP服务器


该项目实现了 模型上下文协议 （MCP） 用于交互的服务器 这 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模型注册表项
• 模型版本 -版本化模型工件

已弃用（建议迁移）

• ~~管道运行模板~~→ use 快照 相反（参见 迁移指南)

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

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

可用工具

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

管道执行（v1.2中的新功能）

组织（v1.2中的新功能）

核心实体

交互式应用程序（实验）

分析工具

诊断

弃用的工具

迁移：运行模板→ 快照

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

快速迁移指南

示例工作流（快照优先）

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

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

• 预配置片段 用于您的特定服务器URL和凭据
• 一键安装 通过支持的IDE的深度链接
• 复制粘贴配置 适用于VS Code、Claude Desktop、Cursor、Claude Code、OpenAI Codex等
• Docker和uv选项 根据您的喜好

ZenML Pro用户

MCP设置页面允许您通过单击生成个人访问令牌（PAT）。令牌会自动包含在所有生成的配置代码段中。

ZenML OSS用户

1. 首先通过以下方式创建服务帐户令牌 设置→ 服务账户
2. 将令牌粘贴到MCP设置页面
3. 复制IDE生成的配置

______________________________________________________________________

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

MCP应用程序（实验）

什么是MCP应用程序？ MCP应用程序是MCP服务器可以使用的交互式HTML UI 直接服务于AI客户端。它们在沙盒iframe中呈现，并可以调用 服务器工具双向。看 官方公告 了解全部细节。

Run Activity Chart

此服务器包括两个实验性MCP应用程序：

Pipeline Runs Dashboard

这些应用程序作为概念验证示例包含在内。我们欢迎对更多MCP应用程序的反馈和贡献。这个新功能还处于早期阶段，所以我们必须看看它是如何发展的。我们希望今后更充分地支持它。

支持的客户

MCP应用程序需要 流式HTTP 运输（非stdio）。以下客户 目前支持MCP应用程序：

• ✅ VS Code （内部人士版）
• ✅ 鹅
• ✅ ChatGPT （即将推出）
• ⚠️ 克劳德桌面版 --截至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 是必需的——没有它，管道运行工具将

失败，显示“当前没有项目设置为活动”

• 这 --disable-dns-rebinding-protection 跟在后面跑时需要旗子

反向代理（cloudflared、ngrok）——当代理处理安全问题时是安全的

• 每次重启时，隧道URL都会发生变化——相应地更新您的客户端集成

测试和质量保证

该项目包括自动化测试，以确保MCP服务器保持正常运行：

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

自动化测试验证：

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

使用MCP检查器进行调试

对于交互式调试，请使用 MCP检查员 --一个基于网络的工具，可以让您实时测试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 ZENML_STORE_URL （URL本身从不作为事件属性发送）。

其他分析选项：

• ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S --关机期间同步刷新分析的最长时间（秒）（默认值：1.0）

关机跟踪注意事项： 关闭事件与有界超时同步发送，以获得最佳的交付可靠性。但是，如果容器被杀死 SIGKILL （例如。， docker kill)，关机处理程序无法启动——这是Docker/OS的限制，而不是bug。

启动验证

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

# 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 文档. 我们建议通过他们的安装程序脚本或通过 brew 如果使用a 雨衣。（从技术上讲，你没有 *需要* 它，但它使安装和设置变得容易。)

您还需要在本地某处克隆此存储库：

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

您的MCP配置文件

MCP配置文件是一个JSON文件，它告诉MCP客户端如何连接到 您的MCP服务器。不同的MCP客户端将以不同的方式使用或指定此选项。二 常用的MCP客户端是 克劳德桌面版 和 光标，我们提供安装说明 在......下面

您需要按照以下格式指定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 file（这是在以下情况下运行的文件

您连接到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的预配置安装说明和深度链接。

您需要使用最新版本的 克劳德桌面版 安装。

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

注：MCP捆绑包(.mcpb)替换旧的桌面扩展(.dxt)格式；现有的 .dxt 文件仍然在Claude Desktop中工作。

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

为了更好地体验ZenML工具的结果，您可以将Claude配置为 以更易读的格式显示JSON响应。在Claude Desktop中，转到 设置→ 个人资料，以及“克劳德应该考虑哪些个人偏好” 作为回应？“部分，添加以下内容（或使用这些精确 话！):

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的工作方式与Claude Desktop略有不同，因为您可以指定 每个存储库的配置文件。这意味着，如果你想使用 ZenML MCP服务器位于多个存储库中，您需要在中指定配置文件 他们每个人。

要为单个存储库设置它，您需要：

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

根据我们的经验，有时它会显示一个红色的错误指示器，即使它是 工作。您可以通过在光标聊天窗口中聊天来尝试。它会让 你知道是否能够访问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 Bundles(.mcpb)--Anthropic桌面扩展（DXT）的继任者。MCP Bundles将整个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，因此您可以安装或发现 ZenML MCP服务器 直接在支持注册表的任何地方（例如Claude Desktop的扩展目录）。

• 始终保持最新： 注册表项会随着标记提交的每次发布而刷新 manifest.json 和 server.json.
• 备选安装路径： 您仍然可以通过打包的 .mcpb bundle（见上文）或运行Docker镜像。

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

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