ZenML

ZenML 的 MCP 伺服器

此專案實作了一個 Model Context Protocol (MCP) 伺服器，用於與 ZenML API 互動。

什麼是 MCP？

Model Context Protocol (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 模型登錄項目
• 模型版本 - 版本化模型成品

相容性 API（建議遷移）

• 管線執行範本在 ZenML 0.97.0 中仍可使用，但新工作流程建議使用快照（請參閱遷移指南）

此伺服器也允許您使用快照（建議）或已棄用的範本式觸發參數觸發新的管線執行。

注意：我們會根據使用者回饋持續改善此整合。 歡迎加入我們的 Slack 社群，分享您的使用經驗， 並協助我們讓它變得更好！

工具設定檔與寫入政策

預設的 compact 設定檔會公布 16 個工具。七個通用工具涵蓋資源目錄、讀取、一般變更和有限的生命週期操作：

工具	用途
zenml_describe_resources	探索支援的資源類型和受限的操作結構描述
zenml_list_resources	使用經驗證的篩選條件和分頁列出一種資源類型
zenml_get_resource	取得單一資源；必要時指定父項和專案範圍
zenml_create_resource	使用具型別的承載資料建立支援的資源
zenml_update_resource	更新一個指定的資源 UUID
zenml_delete_resource	刪除或封存一個指定的資源 UUID
zenml_action_resource	執行允許清單中的生命週期或關聯操作，不進行重試

另外保留九個專用工具，因為它們提供診斷、作用中上下文、串流記錄或程式碼、管線執行，或互動式 App：

• diagnose_zenml_setup
• get_active_user 和 get_active_project
• trigger_pipeline
• get_step_logs、get_step_code 和 get_deployment_logs
• open_pipeline_run_dashboard 和 open_run_activity_chart

get_step_logs 最多會傳回 50,000 筆項目，依時間由舊到新排列，並附上 possibly_truncated 旗標，以及說明缺少哪些項目和原因的 note。 傳入 tail 可只取得最新項目。在 ZenML 0.97+ 伺服器上，它會分頁讀取記錄儲存區；在 0.96 上則使用較舊的單次請求端點。

如果現有用戶端仍依賴舊的實體專用名稱（例如 list_pipeline_runs），請使用 ZENML_MCP_PROFILE=legacy。這會保留 ZenML 0.97.0 的既有工具名稱和結構描述相容層，但不會新增對較舊 ZenML 伺服器版本的支援。請只在遷移期間使用；舊版回應格式可能會公開比精簡工具更多的操作中繼資料，不過伺服器會在兩種設定檔中省略含有憑證的設定和其他敏感欄位。

工具註冊與寫入存取權彼此獨立：

設定檔	政策	公布的工具
compact	read_write	16
compact	read_only	11
legacy	read_write	57
legacy	read_only	52

將 ZENML_MCP_WRITE_POLICY=read_only 設為可移除所有四個通用變更工具， 並從 MCP 探索和分派中移除 trigger_pipeline。資源探索也會省略建立、更新、刪除和操作結構描述。舊的 ZENML_MCP_READ_ONLY=true 設定仍可使用；無效的政策值會安全地回退至唯讀模式。無效的 ZENML_MCP_PROFILE 會使啟動因設定錯誤而停止。

2.0.0 版需要 MCP Python SDK 2.2.0 和 ZenML 0.96.4。精簡設定檔是新的預設值，對呼叫實體專用工具名稱的用戶端而言，這是破壞性探索變更。遷移這些用戶端時，請設定 ZENML_MCP_PROFILE=legacy，然後將每個呼叫改用通用資源工具。

變更結果會區分 completed、accepted 和 unknown 狀態。 如果變更可能已送達 ZenML，伺服器不會重試。若結果為已接受或未知，請先依照回應中的調和指示操作，再決定是否再次呼叫。若有具名讀取工具可用，請使用該工具。建立 Webhook 和輪替密鑰可能會傳回一次新的簽署密鑰；之後的讀取不會再顯示該密鑰。刪除結構描述會說明操作是封存中繼資料、移除中繼資料、解除佈建執行中的資源，還是可能刪除已儲存的成品資料。

第一個 2.0 版本涵蓋專案、堆疊和元件、風格、服務、管線和執行、快照和範本、部署、成品和版本、模型和版本、標籤、連接器、程式碼儲存庫、Webhook、觸發器、等待條件和 Hook 呼叫的一般操作。使用者、排程、服務連接器類型、密鑰和資源請求則提供 zenml_describe_resources 所示的唯讀支援範圍。此版本不包含 ZenML Cloud 控制平面管理、Resource Manager 管理、使用者和憑證管理、密鑰值 CRUD、連接器登入和驗證、原始 Webhook 事件，以及彙總式偵錯或沿襲工具。

開始通用工作流程時，先探索精確的結構描述，再呼叫工具：

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,
)

兩種設定檔都提供提示和資源。分析提示、受限的資源結構描述端點，以及 most_recent_runs 都是 MCP 提示或資源，而非工具。

執行範本相容性

ZenML 0.97.0 保留執行範本 CRUD API。新工作流程建議使用快照。管線便利建立功能和範本式觸發參數已棄用。在舊版設定檔中，get_run_template 和 list_run_templates 仍可供現有用戶端使用。

舊版 tag 輸入仍保留在 list_run_templates 中，以維持結構描述相容性，但 ZenML 0.97.0 沒有對應的伺服器端篩選器。非 null 值會在呼叫 SDK 前遭到拒絕。快照標籤篩選仍可使用。

遷移：執行範本 → 快照

為什麼要變更？ 快照已取代執行範本，成為 ZenML 建議使用的可執行管線成品。0.97.0 SDK 仍支援執行範本 CRUD，但新程式碼應使用快照。

快速遷移指南

舊版模式（範本）	精簡模式（快照）
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=...)

範例工作流程（以快照為優先）

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)

若要在觸發可執行快照時覆寫參數，請傳入 ZenML 執行設定（快照本身不會變更）：

trigger_pipeline(
    snapshot_name_or_id="my-snapshot",
    run_configuration={
        "steps": {"train": {"parameters": {"learning_rate": 0.01}}},
        "enable_cache": False,
    },
)

對於靜態快照，請如上所示覆寫步驟參數。頂層的 run_configuration={"parameters": {...}} 會覆寫管線函式參數， 且僅支援動態快照；ZenML 會拒絕將其用於靜態快照。

注意： get_deployment_logs 會傳回有上限的輸出（預設 100 行，最多 1000 行，上限為 100KB），且需要安裝適當的 deployer 整合。

透過儀表板快速設定（建議）

透過 ZenML 儀表板的 MCP Settings 頁面設定 ZenML MCP Server，是最簡單的方式。

前往 ZenML 儀表板中的 Settings → MCP，即可取得：

• 適用於您特定伺服器 URL 和憑證的預先設定片段
• 透過深層連結為支援的 IDE 一鍵安裝
• 適用於 VS Code、Claude Desktop、Cursor、Claude Code、OpenAI Codex 等工具的複製貼上設定
• 可依偏好選擇的 Docker 和 uv 選項

ZenML Pro 使用者

MCP Settings 頁面可讓您一鍵產生個人存取權杖 (PAT)。此權杖會自動包含在所有產生的設定片段中。

ZenML OSS 使用者

1. 先透過 Settings → Service Accounts 建立服務帳戶權杖
2. 將權杖貼到 MCP Settings 頁面
3. 複製為 IDE 產生的設定

---

偏好手動設定？ 請參閱下方的詳細說明。

MCP Apps（實驗性）

什麼是 MCP Apps？ MCP Apps 是 MCP 伺服器可直接提供給 AI 用戶端的互動式 HTML UI。它們會在沙箱 iframe 中呈現，並可雙向呼叫伺服器工具。完整資訊請參閱官方公告。

此伺服器包含兩個實驗性 MCP Apps：

App	工具	說明
管線執行儀表板	open_pipeline_run_dashboard	互動式表格，顯示近期管線執行的狀態、步驟詳細資料和記錄
執行活動圖表	open_run_activity_chart	長條圖，顯示過去 30 天的管線執行活動及狀態分類

這些 App 是概念驗證範例。我們歡迎您提供意見回饋，並貢獻更多 MCP Apps。這項新功能仍處於早期階段，未來發展仍有待觀察。我們預期未來會更全面地支援它。

支援的用戶端

MCP Apps 需要 Streamable HTTP 傳輸（不支援 stdio）。目前支援 MCP Apps 的用戶端如下：

• ✅ VS Code（Insiders Edition）
• ✅ Goose
• ✅ ChatGPT（即將推出）
• ⚠️ Claude Desktop -- 截至 2026 年 1 月下旬，尚未呈現 Apps。
• ⚠️ Claude.ai（網頁版）— 截至 2026 年 1 月下旬，尚未呈現 Apps。

注意： 撰寫本文時，我們無法使用 Claude Desktop 或 Claude.ai 進行完整測試。如果您遇到問題，請回報問題。

使用 Docker 執行 MCP Apps

MCP Apps 使用 Streamable HTTP。請將容器連接埠綁定至 loopback，並在允許遠端存取前，於其前方設定已驗證的反向 Proxy 或具身分識別感知能力的存取服務。Host 和 Origin 驗證可防止 DNS rebinding，但不會驗證呼叫者身分。

1. 建置並執行 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. 設定經驗證的遠端存取：

建立具名的 Cloudflare Tunnel、具有存取控制的 Tailscale Funnel，或同等的經驗證反向代理。將其私人來源指向 http://127.0.0.1:8001，要求公用主機名稱提供身分或服務憑證，並且只將經驗證的請求傳送至來源。設定 MCP 用戶端使用供應商支援的 OAuth 流程或授權標頭。

在將 ZenML 憑證加入容器之前，請確認未經驗證的請求無法連線至 MCP：

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

回應必須是存取供應商的 401、403 或登入重新導向。JSON-RPC 或 MCP 回應表示邊界防護未開啟，必須先修正。

3. 連線經驗證的用戶端：

{
	"servers": {
		"ZenML": {
			"url": "https://mcp.example.com/mcp",
			"type": "http"
		}
	},
	"inputs": []
}

• 請 AI「開啟 pipeline runs 儀表板」或「顯示 run activity 圖表」

重要注意事項：

• 必須設定 ZENML_ACTIVE_PROJECT_ID，否則 pipeline run 工具會因「No project is currently set as active」而失敗
• 只有在經驗證的代理伺服器會驗證公用主機，且容器連接埠仍僅限 loopback 存取時，才適合使用 --disable-dns-rebinding-protection
• 將 ZenML API 金鑰的權限限制在 MCP 用戶端所需範圍；僅供檢查的用戶端請使用 ZENML_MCP_WRITE_POLICY=read_only

測試與品質保證

此專案包含自動化測試，以確保 MCP 伺服器持續正常運作：

• 🔄 自動化冒煙測試：GitHub Actions 每 3 天執行一次完整的冒煙測試
• 🚨 建立問題：測試失敗時會自動建立 GitHub issue，並附上詳細的偵錯資訊
• ⚡ 快速 CI：使用 UV 搭配快取，快速安裝相依套件並執行測試
• 🧪 手動測試：你可以使用 uv run scripts/test_mcp_server.py server/zenml_server.py 在本機執行冒煙測試

自動化測試會驗證：

• MCP 通訊協定連線與交握
• 伺服器初始化與工具探索
• 基本工具功能（ZenML 伺服器可連線時）
• 資源與提示列舉
• 即使在受限環境中，diagnose_zenml_setup 仍會傳回結構化診斷資訊

不需憑證的 CI 會透過 MCP 通訊協定涵蓋每個介接器。PR 與 release CI 也會在 loopback 位址啟動全新的 ZenML 0.97.0 OSS 伺服器，並 執行持久化 CRUD 與同名專案隔離收據。伺服器使用暫存設定與資料庫，工作結束時會移除；不需要存取儲存庫環境、自架 runner 或 ZenML 憑證。

ZenML 的本機 OSS 伺服器會停用驗證，而其 SQL 儲存區不支援 pipeline 重播或外部部署基礎架構。因此，受限存取以及啟用功能的觸發、重播、部署、等待條件與資源請求收據，仍是獨立的選擇性閘門。這些測試分別需要 ZENML_MCP_RESTRICTED_INTEGRATION=1 搭配 ZENML_MCP_RESTRICTED_API_KEY，或 ZENML_MCP_ACTION_INTEGRATION=1 搭配 ZENML_MCP_ACTION_FIXTURE 中完全相符的暫用 fixture UUID。略過閘門不代表這些功能已通過測試。操作人員可以設定 ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1，將缺少選擇性閘門的情況改為失敗。預設測試執行絕不會佈建雲端基礎架構。

使用 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 — 只要按一下 Connect，並使用 Tools 分頁即可互動測試任何工具。

如需更詳細的偵錯說明，請參閱 CLAUDE.md。

隱私與分析

ZenML MCP Server 會收集匿名使用分析資料，協助我們改進產品。

我們會追蹤：

• 使用哪些工具及其使用頻率
• 錯誤率與類型（僅錯誤類型，不含訊息）
• 基本環境資訊（OS、Python 版本，以及是否在 Docker/CI 中執行）
• 工作階段持續時間與工具使用模式

我們不會收集：

• 你的 ZenML 伺服器 URL 或 API 金鑰
• Pipeline 名稱、模型名稱或任何業務資料
• 錯誤訊息或堆疊追蹤
• 任何可識別個人身分的資訊

停用分析：

# 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/OS 的限制，並非錯誤。

啟動驗證

你可以啟用輕量級的啟動診斷檢查：

# 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 Settings 頁面，以最簡便的方式完成設定。

**相容性：**目前版本已針對 ZenML 0.97.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",
                "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"
            }
        }
    }
}

提供 ZENML_STORE_API_KEY 時，MCP 伺服器會將 ZenML 憑證保存在記憶體中，不會讀取或更新 zenml login 儲存的憑證。這適用於直接執行 Python、MCPB 擴充功能與 Docker。未提供 API 金鑰的連線仍可使用已儲存的終端機登入資訊。變更 API 金鑰後，請重新啟動 MCP 伺服器；僅開啟新聊天可能仍會沿用正在執行的伺服器程序。

有四個虛設值需要替換：

• 本機安裝的 uv 路徑（如果你透過 brew 在 Mac 上安裝，以上列出的路徑就是其所在位置）
• zenml_server.py 檔案的路徑（連線至 MCP 伺服器時會執行此檔案）。此檔案位於此儲存庫的根目錄。你需要指定此檔案的完整確切路徑。
• ZenML 伺服器 URL（即 ZenML 伺服器的 URL。你可以在 ZenML Cloud UI 中找到它）。格式大致如下：https://d534d987a-zenml.cloudinfra.zenml.io。
• ZenML 伺服器 API 金鑰（即 ZenML 伺服器的 API 金鑰。你可以在 ZenML Cloud UI 中找到它，或https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account，了解如何建立金鑰。對於 ZenML MCP 伺服器，我們建議使用服務帳戶。）

你可以自行變更執行 MCP 伺服器 Python 檔案的方式，但使用 uv 可能是最簡單的選項，因為它會為你處理環境與相依套件安裝。

安裝以搭配 Claude Desktop 使用

**快速替代方式：**使用 ZenML 儀表板中的 MCP Settings 頁面（Settings → MCP），取得預先設定的安裝說明與 Claude Desktop 深層連結。

你需要安裝最新版的 Claude Desktop。

你只要開啟 Settings 選單，並將此儲存庫根目錄中的 mcp-zenml.mcpb 檔案拖曳至選單，即可依照指示完成安裝與設定。你需要新增 ZenML 伺服器 URL 與 API 金鑰。

注意：MCP bundles（.mcpb）已取代較舊的 Desktop Extensions（.dxt）格式；現有的 .dxt 檔案仍可在 Claude Desktop 中使用。

選用：改善 ZenML 工具輸出顯示方式

若要更方便地查看 ZenML 工具結果，你可以設定 Claude，以更易讀的格式顯示 JSON 回應。在 Claude Desktop 中，前往 Settings → Profile，並在「What personal preferences should Claude consider in responses?」區段中加入類似以下內容（也可以直接使用這些文字！）：

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 Settings 頁面（Settings → MCP）可產生已預先填入憑證的確切 mcp.json 內容。

你需要安裝 Cursor。

Cursor 的運作方式與 Claude Desktop 略有不同：你需要針對每個儲存庫指定設定檔。這表示如果你想在多個儲存庫中使用 ZenML MCP 伺服器，就需要在每個儲存庫中指定設定檔。

若要為單一儲存庫設定，你需要：

• 在儲存庫根目錄建立 .cursor 資料夾
• 在其中建立 mcp.json 檔案，並填入上述內容
• 前往 Cursor 設定，按一下 ZenML 伺服器旁的「enable」。

根據我們的經驗，即使伺服器正常運作，有時仍會顯示紅色錯誤指示。你可以在 Cursor 聊天視窗中試著對話。它會告訴你是否能存取 ZenML 工具。

Docker 映像

你可以將伺服器作為 Docker 容器執行。此程序透過 stdio 通訊，因此會等待 MCP 用戶端連線。請透過環境變數傳入 ZenML 憑證。

預先建置的映像（Docker Hub）

拉取最新的多架構映像：

docker pull zenmldocker/mcp-zenml:latest

版本化的發行版本會標記為 X.Y.Z：

docker pull zenmldocker/mcp-zenml:2.0.0

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

在本機建置

在儲存庫根目錄執行：

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 Bundles (.mcpb)

此專案使用 MCP Bundles（.mcpb）— 這是 Anthropic Desktop Extensions (DXT) 的後繼格式。MCP Bundles 會將整個 MCP 伺服器（包括相依套件）封裝成單一檔案，並提供方便使用者的設定方式。

重新命名注意事項：MCP Bundles 已取代較舊的 .dxt 格式。Claude Desktop 仍向下相容現有的 .dxt 檔案，但我們現在提供 mcp-zenml.mcpb，並建議今後使用此格式。

儲存庫根目錄中的 mcp-zenml.mcpb 檔案使用 MCPB 0.4 UV 執行環境。 主機會為目前的作業系統安裝已固定版本的 Python 相依套件，因此同一個 bundle 可在 macOS、Windows 與 Linux 上使用，無須內嵌平台專屬的原生擴充功能。首次由 UV 解析 bundle 環境時需要網路連線。 Bundle 建置會重用已提交的 mcpb-uv.lock，並以離線模式解析其 Python 相依性圖。Bundle 的相依性清單來自 pyproject.toml 中的 [project].dependencies。變更該清單後，設定 MCPB_REFRESH_LOCK=1，即可在線上重新解析，同時保留所有仍符合條件的固定版本；MCPB_REFRESH_LOCK=upgrade 則會將所有固定版本更新至最新版本。

將 .mcpb 檔案拖放到 Claude Desktop 的設定中時，它會自動處理：

• 執行階段相依性安裝
• 安全的設定管理
• 跨平台相容性
• 使用者友善的設定流程

如需更多資訊，請參閱 Anthropic 在其文件中發布的 Desktop Extensions (DXT) 公告，以及相關的 MCP bundle 封裝指南：https://www.anthropic.com/engineering/desktop-extensions

已發布至 Anthropic MCP Registry

此 MCP 伺服器已發布至官方 Anthropic MCP Registry，並可供相容的主機探索。每次標記版本發布時，我們的 CI 都會透過 GitHub OIDC，使用 Registry 的 mcp-publisher CLI 更新 Registry 項目，讓你可以在支援 Registry 的任何地方（例如 Claude Desktop 的 Extensions 目錄）直接安裝或探索 ZenML MCP Server。

• **永遠保持最新：**每次發布時，Registry 項目都會使用標記提交的 manifest.json 和 server.json 重新整理。
• **其他安裝方式：**你仍可透過封裝的 .mcpb bundle 在本機安裝（見上文），或執行 Docker 映像檔。

在此深入了解 Registry：

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