ZenML的MCP服务器
该项目实现了 模型上下文协议
(MCP) 用于交互的服务器
这 ZenML API
什么是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中的新功能)
| 工具 | 说明 |
|---|---|
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 App) |
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=...) |
示例工作流(快照优先)```
-
Discover project context:
→ get_active_project() -
Find runnable snapshots:
→ list_snapshots(runnable=True, named_only=True) -
Trigger a run:
→ trigger_pipeline(pipeline_name_or_id="my-pipeline", snapshot_name_or_id="my-snapshot") -
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** 在ZenML仪表板中获取:
- **预配置片段** 用于您的特定服务器URL和凭据
- **一键安装** 通过支持的IDE的深度链接
- **复制粘贴配置** 适用于VS Code、Claude Desktop、Cursor、Claude Code、OpenAI Codex等
- **Docker和uv选项** 根据您的喜好
### ZenML Pro用户
MCP设置页面允许您通过单击生成个人访问令牌(PAT)。令牌会自动包含在所有生成的配置代码段中。
### ZenML OSS用户
1. 首先通过以下方式创建服务帐户令牌 **设置→ 服务账户**
1. 将令牌粘贴到MCP设置页面
1. 复制IDE生成的配置
______________________________________________________________________
**更喜欢手动设置?** 请参阅下面的详细说明。
## MCP应用程序(实验)
> **什么是MCP应用程序?** MCP应用程序是MCP服务器可以使用的交互式HTML UI
> 直接服务于AI客户端。它们在沙盒iframe中呈现,并可以调用
> 服务器工具双向。看 官方公告
> 了解全部细节。
此服务器包括两个实验性MCP应用程序:
|应用程序|工具|描述|
|-----|------|-------------|
| **管道运行仪表板** | `open_pipeline_run_dashboard` |最近管道运行的交互式表,包括状态、步骤详细信息和日志|
| **运行活动图表** | `open_run_activity_chart` |过去30天管道运行活动的柱状图,并附有状态细分|
这些应用程序作为概念验证示例包含在内。我们欢迎对更多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容器:**```bash
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隧道(用于云客户端):```bash
npx cloudflared tunnel --url http://localhost:8001
这将打印一个公共URL,如下所示 `https://random-words.trycloudflare.com`.
**3.连接您的客户端:**
- 在Claude Desktop或其他客户端中,使用URL添加MCP服务器:
`https://random-words.trycloudflare.com/mcp` 例如。:```json
{
"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工具:```bash
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密钥
- 管道名称、型号名称或任何业务数据
- 错误消息或堆栈跟踪
- 任何个人身份信息
**要禁用分析,请执行以下操作:**```bash
# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false
# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true
对于调试/测试(将事件记录到stderr而不是发送):```bash
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。
### 启动验证
您可以启用轻量级启动诊断检查:```bash
# 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
雨衣。(从技术上讲,你没有 需要 它,但它使安装和设置变得容易。)
您还需要在本地某处克隆此存储库:```bash
git clone https://github.com/zenml-io/mcp-zenml.git
### 您的MCP配置文件
MCP配置文件是一个JSON文件,它告诉MCP客户端如何连接到
您的MCP服务器。不同的MCP客户端将以不同的方式使用或指定此选项。二
常用的MCP客户端是 克劳德桌面版 和
光标,我们提供安装说明
在......下面
您需要按照以下格式指定ZenML MCP服务器:```json
{
"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.pyfile(这是在以下情况下运行的文件
您连接到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中,转到
设置→ 个人资料,以及“克劳德应该考虑哪些个人偏好”
作为回应?“部分,添加以下内容(或使用这些精确
话!):```markdown
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)
拉取最新的多拱形图像:```bash
docker pull zenmldocker/mcp-zenml:latest
版本发布标记为 X.Y.Z:```bash
docker pull zenmldocker/mcp-zenml:1.0.8
使用ZenML凭据运行(stdio模式):```bash
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配置```json
{
"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"
]
}
}
}
### 本地建设
从存储库根目录:```bash
docker build -t zenmldocker/mcp-zenml:local .
运行本地生成的映像:bash
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. - 备选安装路径: 您仍然可以通过打包的
.mcpbbundle(见上文)或运行Docker镜像。
在此处了解有关注册表的更多信息:
- Anthropic MCP注册表(社区仓库):https://github.com/modelcontextprotocol/registry
