ZenML MCP Server

官方

透過你的 ZenML MCP 伺服器與你的 MLOps 和 LLMOps 管道互動

GitHub

文件

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 應用程式是互動式 HTML UI，MCP 伺服器可以直接將其提供給 AI 用戶端。它們在沙箱化的 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——一個基於網頁的工具，讓您可以即時測試 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

這會開啟一個已預先填入您憑證的網頁 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 檔案，伺服器將會退而使用從 ZENML_STORE_URL 的雜湊值所衍生的確定性匿名 UUID（該 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 會使用 GitHub OIDC，透過登錄庫的 mcp-publisher CLI 更新登錄庫條目，因此您可以直接在任何支援該登錄庫的地方（例如 Claude Desktop 的擴充功能目錄）安裝或探索 ZenML MCP 伺服器。

始終保持最新： 登錄庫條目會在每次發行時，從標記提交的 manifest.json 和 server.json 進行更新。
替代安裝路徑： 您仍然可以透過封裝的 .mcpb 套件在本機安裝（請參閱上文），或執行 Docker 映像檔。

在此處了解更多關於登錄庫的資訊：

Anthropic MCP 登錄庫（社群儲存庫）：https://github.com/modelcontextprotocol/registry