ZenML
chính thứcTương tác với các pipeline MLOps và LLMOps của bạn thông qua máy chủ ZenML MCP
Bạn có thể làm gì với ZenML MCP?
- Khám phá lược đồ tài nguyên — Hỏi những loại tài nguyên và thao tác nào được hỗ trợ trước khi chạy truy vấn bằng
zenml_describe_resources. - Liệt kê và lọc tài nguyên — Liệt kê các lần chạy pipeline, bản triển khai, ảnh chụp nhanh hoặc mô hình bằng bộ lọc đã được xác thực và phân trang thông qua
zenml_list_resources. - Kiểm tra một tài nguyên — Lấy một tài nguyên theo ID, kèm phạm vi tài nguyên cha và dự án khi cần, bằng
zenml_get_resource. - Kích hoạt một lần chạy pipeline — Bắt đầu một lần chạy từ ảnh chụp nhanh có thể chạy, tùy chọn ghi đè các tham số bước, bằng
trigger_pipeline. - Đọc nhật ký và mã bước — Truy xuất nhật ký bước có giới hạn (dùng
tailđể lấy các mục mới nhất) hoặc mã nguồn bước thông quaget_step_logsvàget_step_code. - Chẩn đoán thiết lập — Chạy
diagnose_zenml_setupđể nhận kết quả khắc phục sự cố có cấu trúc, ngay cả khi thiếu ZenML SDK hoặc biến môi trường.
Tài liệu
MCP Server cho ZenML
Dự án này triển khai một máy chủ Model Context Protocol (MCP) để tương tác với API ZenML.

MCP là gì?
Model Context Protocol (MCP) là một giao thức mở giúp chuẩn hóa cách các ứng dụng cung cấp ngữ cảnh cho Mô hình Ngôn ngữ Lớn (LLM). Giao thức này hoạt động như một “cổng USB-C cho các ứng dụng AI” — cung cấp cách thức chuẩn hóa để kết nối các mô hình AI với nhiều nguồn dữ liệu và công cụ khác nhau.
MCP tuân theo kiến trúc máy khách-máy chủ, trong đó:
- Máy chủ MCP: Các chương trình như Claude Desktop hoặc IDE muốn truy cập dữ liệu thông qua MCP
- Máy khách MCP: Các máy khách giao thức duy trì kết nối 1:1 với máy chủ
- Máy chủ MCP: Các chương trình gọn nhẹ cung cấp những khả năng cụ thể thông qua giao thức chuẩn hóa
- Nguồn dữ liệu cục bộ: Tệp, cơ sở dữ liệu và dịch vụ trên máy tính của bạn mà máy chủ MCP có thể truy cập an toàn
- Dịch vụ từ xa: Các hệ thống bên ngoài có thể truy cập qua internet mà máy chủ MCP có thể kết nối
ZenML là gì?
ZenML là nền tảng mã nguồn mở để xây dựng và quản lý các quy trình ML và AI. Nền tảng này cung cấp giao diện thống nhất để quản lý dữ liệu, mô hình và thử nghiệm.
Để biết thêm thông tin, hãy xem trang web ZenML và tài liệu của chúng tôi.
Tính năng
Máy chủ cung cấp các công cụ MCP để truy cập những chức năng đọc cốt lõi từ máy chủ ZenML, giúp lấy thông tin trực tiếp về:
Thực thể cốt lõi
- Người dùng - tài khoản và quyền của người dùng
- Stack - cấu hình hạ tầng
- Thành phần Stack - các khối cấu thành riêng lẻ của stack
- Flavor - các loại thành phần hiện có
- Trình kết nối dịch vụ - xác thực đám mây
Thực thi quy trình
- Pipeline - định nghĩa pipeline
- Lần chạy Pipeline - lịch sử và trạng thái thực thi
- Bước Pipeline - thông tin chi tiết, mã và nhật ký của từng bước
- Lịch chạy - lịch chạy tự động
- Artifact - siêu dữ liệu về artifact dữ liệu (không bao gồm chính dữ liệu đó)
Triển khai và phục vụ
- Snapshot - cấu hình pipeline đã cố định (artifact “cần chạy/phục vụ nội dung gì”)
- Deployment - các phiên bản phục vụ đang chạy, kèm trạng thái, URL và nhật ký
- Dịch vụ - các endpoint phục vụ mô hình
Tổ chức và khám phá
- Dự án - vùng chứa tài nguyên ZenML theo tổ chức
- Thẻ - nhãn siêu dữ liệu dùng chung để khám phá
- Bản dựng - artifact bản dựng pipeline kèm thông tin về image và mã
Mô hình
- Mô hình - các mục trong sổ đăng ký mô hình ML
- Phiên bản mô hình - artifact mô hình được quản lý theo phiên bản
API tương thích (khuyến nghị di chuyển)
- Mẫu lần chạy Pipeline vẫn khả dụng trong ZenML 0.97.0, nhưng Snapshot được ưu tiên cho quy trình mới (xem Hướng dẫn di chuyển)
Máy chủ cũng cho phép bạn kích hoạt các lần chạy pipeline mới bằng snapshot (được ưu tiên) hoặc tham số kích hoạt dựa trên mẫu đã lỗi thời.
Lưu ý: Chúng tôi liên tục cải thiện tích hợp này dựa trên phản hồi của người dùng. Vui lòng tham gia cộng đồng Slack để chia sẻ trải nghiệm và giúp chúng tôi cải thiện hơn nữa!
Hồ sơ công cụ và chính sách ghi
Hồ sơ compact mặc định công bố 16 công cụ. Bảy công cụ tổng quát bao quát
danh mục tài nguyên, thao tác đọc, thay đổi thông thường và các hành động vòng đời hữu hạn:
| Công cụ | Mục đích |
|---|---|
zenml_describe_resources | Khám phá các loại tài nguyên được hỗ trợ và lược đồ thao tác có giới hạn |
zenml_list_resources | Liệt kê một loại tài nguyên với bộ lọc đã xác thực và phân trang |
zenml_get_resource | Lấy một tài nguyên, kèm phạm vi đối tượng cha và dự án khi cần |
zenml_create_resource | Tạo tài nguyên được hỗ trợ từ payload có kiểu |
zenml_update_resource | Cập nhật một UUID tài nguyên cụ thể |
zenml_delete_resource | Xóa hoặc lưu trữ một UUID tài nguyên cụ thể |
zenml_action_resource | Thực hiện hành động vòng đời hoặc quan hệ trong danh sách cho phép, không thử lại |
Chín công cụ chuyên biệt vẫn được giữ lại vì chúng cung cấp khả năng chẩn đoán, ngữ cảnh đang hoạt động, nhật ký hoặc mã được truyền trực tuyến, thực thi pipeline hoặc App tương tác:
diagnose_zenml_setupget_active_uservàget_active_projecttrigger_pipelineget_step_logs,get_step_code, vàget_deployment_logsopen_pipeline_run_dashboardvàopen_run_activity_chart
get_step_logs trả về tối đa 50,000 mục, theo thứ tự cũ nhất trước, kèm cờ
possibly_truncated, cùng với note cho biết mục nào bị thiếu và
lý do. Truyền tail để chỉ lấy các mục mới nhất. Trên máy chủ ZenML 0.97+,
công cụ này phân trang qua kho nhật ký; trên phiên bản 0.96, công cụ dùng endpoint một yêu cầu cũ hơn.
Dùng ZENML_MCP_PROFILE=legacy khi một máy khách hiện có vẫn phụ thuộc vào các tên
cụ thể theo thực thể cũ như list_pipeline_runs. Tùy chọn này giữ lại lớp tương thích
tên công cụ và lược đồ đã được xác định cho ZenML 0.97.0. Tùy chọn này
không bổ sung hỗ trợ cho các phiên bản máy chủ ZenML cũ hơn. Chỉ dùng trong quá trình
di chuyển: hình dạng phản hồi cũ có thể để lộ nhiều siêu dữ liệu vận hành hơn các công cụ
gọn nhẹ, dù máy chủ loại bỏ cấu hình chứa thông tin xác thực và các trường nhạy cảm khác
trong cả hai hồ sơ.
Việc đăng ký và quyền ghi là độc lập:
| Hồ sơ | Chính sách | Công cụ được công bố |
|---|---|---|
compact | read_write | 16 |
compact | read_only | 11 |
legacy | read_write | 57 |
legacy | read_only | 52 |
Đặt ZENML_MCP_WRITE_POLICY=read_only để loại bỏ cả bốn công cụ thay đổi tổng quát
và trigger_pipeline khỏi quá trình khám phá và điều phối MCP. Việc khám phá tài nguyên cũng
bỏ qua các lược đồ tạo, cập nhật, xóa và hành động. Cài đặt cũ
ZENML_MCP_READ_ONLY=true vẫn được chấp nhận; các giá trị chính sách không hợp lệ sẽ mặc định an toàn về chế độ chỉ đọc. Giá trị
ZENML_MCP_PROFILE không hợp lệ sẽ khiến quá trình khởi động dừng lại với lỗi cấu hình.
Phiên bản 2.0.0 yêu cầu MCP Python SDK 2.2.0 và ZenML 0.96.4. Hồ sơ gọn nhẹ
là mặc định mới và tạo ra thay đổi không tương thích trong quá trình khám phá đối với các máy khách
gọi tên công cụ cụ thể theo thực thể. Đặt ZENML_MCP_PROFILE=legacy trong khi di chuyển
các máy khách đó, sau đó chuyển từng lệnh gọi sang các công cụ tài nguyên tổng quát.
Kết quả thay đổi phân biệt các trạng thái completed, accepted, và unknown.
Máy chủ không thử lại một thay đổi sau khi yêu cầu có thể đã đến ZenML. Với kết quả được chấp nhận
hoặc chưa xác định, hãy làm theo hướng dẫn đối soát trong phản hồi trước khi quyết định có gọi lại hay không.
Dùng thao tác đọc có tên nếu có. Việc tạo webhook và xoay vòng secret có thể trả về secret ký mới một lần;
các lần đọc sau sẽ không hiển thị secret đó. Lược đồ xóa nêu rõ thao tác sẽ lưu trữ siêu dữ liệu,
xóa siêu dữ liệu, hủy cấp phát tài nguyên đang hoạt động hay có thể xóa dữ liệu artifact đã lưu trữ.
Bản phát hành 2.0 đầu tiên bao gồm các thao tác thông thường cho dự án, stack và thành phần,
flavor, dịch vụ, pipeline và lần chạy, snapshot và mẫu, deployment, artifact và phiên bản,
mô hình và phiên bản, thẻ, trình kết nối, kho mã, webhook, trigger, điều kiện chờ và lệnh gọi hook.
Người dùng, lịch chạy, loại trình kết nối dịch vụ, secret và yêu cầu tài nguyên có phạm vi chỉ đọc
như được thể hiện trong zenml_describe_resources. Phạm vi này không bao gồm quản trị mặt phẳng điều khiển ZenML
Cloud, quản trị Resource Manager, quản trị người dùng và thông tin xác thực, CRUD giá trị secret,
đăng nhập và xác minh trình kết nối, sự kiện webhook thô hoặc các công cụ gỡ lỗi và dòng dữ liệu tổng hợp.
Bắt đầu quy trình tổng quát bằng cách khám phá lược đồ chính xác, sau đó gọi công cụ:
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,
)
Prompt và tài nguyên vẫn khả dụng trong cả hai hồ sơ. Các prompt phân tích,
endpoint lược đồ tài nguyên có giới hạn và most_recent_runs là prompt hoặc
tài nguyên MCP, không phải công cụ.
Tương thích với mẫu lần chạy
ZenML 0.97.0 vẫn giữ các API CRUD cho mẫu lần chạy. Snapshot được ưu tiên cho
quy trình mới. Việc tạo pipeline tiện ích và tham số kích hoạt dựa trên mẫu
đã lỗi thời. Trong hồ sơ cũ, get_run_template và
list_run_templates vẫn khả dụng cho các máy khách hiện có.
Đầu vào cũ tag vẫn nằm trong list_run_templates để tương thích lược đồ,
nhưng ZenML 0.97.0 không có bộ lọc tương đương phía máy chủ. Giá trị khác null sẽ bị
từ chối trước khi gọi SDK. Lọc snapshot theo thẻ vẫn khả dụng.
Di chuyển: Mẫu lần chạy → Snapshot
Vì sao có thay đổi này? Snapshot đã thay thế mẫu lần chạy làm artifact pipeline có thể chạy được mà ZenML ưu tiên. SDK 0.97.0 vẫn hỗ trợ CRUD mẫu lần chạy, trong khi mã mới nên dùng snapshot.
Hướng dẫn di chuyển nhanh
| Mẫu cũ (Templates) | Mẫu gọn nhẹ (Snapshots) |
|---|---|
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=...) |
Quy trình ví dụ (ưu tiên Snapshot)
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)
Để ghi đè tham số khi kích hoạt snapshot có thể chạy, hãy truyền cấu hình lần chạy ZenML (bản thân snapshot vẫn không thay đổi):
trigger_pipeline(
snapshot_name_or_id="my-snapshot",
run_configuration={
"steps": {"train": {"parameters": {"learning_rate": 0.01}}},
"enable_cache": False,
},
)
Với snapshot tĩnh, hãy ghi đè tham số bước như minh họa ở trên. Các giá trị ghi đè
run_configuration={"parameters": {...}} cấp cao nhất sẽ ghi đè tham số hàm pipeline
và chỉ được hỗ trợ cho snapshot động; ZenML từ chối giá trị này đối với snapshot tĩnh.
Lưu ý: get_deployment_logs trả về đầu ra có giới hạn (mặc định 100 dòng, tối đa 1000, giới hạn 100KB) và yêu cầu phải cài đặt tích hợp deployer phù hợp.
Thiết lập nhanh qua Dashboard (Khuyến nghị)
Cách dễ nhất để thiết lập ZenML MCP Server là thông qua trang MCP Settings trên dashboard ZenML của bạn.

Truy cập Settings → MCP trong dashboard ZenML để nhận:
- Đoạn cấu hình được thiết lập sẵn cho URL máy chủ và thông tin xác thực cụ thể của bạn
- Cài đặt bằng một cú nhấp thông qua liên kết sâu cho các IDE được hỗ trợ
- Cấu hình sao chép và dán cho VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex và nhiều ứng dụng khác
- Tùy chọn Docker và uv theo sở thích của bạn
Người dùng ZenML Pro
Trang MCP Settings cho phép bạn tạo Personal Access Token (PAT) chỉ bằng một cú nhấp. Token sẽ tự động được đưa vào tất cả các đoạn cấu hình được tạo.
Người dùng ZenML OSS
- Trước tiên, tạo token tài khoản dịch vụ qua Settings → Service Accounts
- Dán token vào trang MCP Settings
- Sao chép cấu hình được tạo cho IDE của bạn
Muốn thiết lập thủ công? Xem hướng dẫn chi tiết bên dưới.
MCP Apps (Thử nghiệm)
MCP Apps là gì? MCP Apps là giao diện HTML tương tác mà máy chủ MCP có thể cung cấp trực tiếp cho các máy khách AI. Chúng hiển thị trong iframe sandbox và có thể gọi công cụ máy chủ theo cả hai chiều. Xem thông báo chính thức để biết đầy đủ chi tiết.

Máy chủ này bao gồm hai MCP Apps thử nghiệm:
| App | Công cụ | Mô tả |
|---|---|---|
| Bảng điều khiển lần chạy Pipeline | open_pipeline_run_dashboard | Bảng tương tác về các lần chạy pipeline gần đây, kèm trạng thái, thông tin chi tiết về bước và nhật ký |
| Biểu đồ hoạt động lần chạy | open_run_activity_chart | Biểu đồ cột về hoạt động chạy pipeline trong 30 ngày qua, phân loại theo trạng thái |

Các app này được đưa vào làm ví dụ chứng minh khái niệm. Chúng tôi hoan nghênh phản hồi và đóng góp để có thêm MCP Apps. Tính năng mới này vẫn còn ở giai đoạn đầu, nên chúng ta sẽ cần chờ xem nó phát triển ra sao. Chúng tôi dự kiến sẽ hỗ trợ đầy đủ hơn trong tương lai.
Máy khách được hỗ trợ
MCP Apps yêu cầu phương thức truyền tải Streamable HTTP (không phải stdio). Các máy khách sau hiện hỗ trợ MCP Apps:
- ✅ VS Code (Insiders Edition)
- ✅ Goose
- ✅ ChatGPT (sắp ra mắt)
- ⚠️ Claude Desktop -- tính đến cuối tháng 1 năm 2026, vẫn chưa hiển thị Apps.
- ⚠️ Claude.ai (web) — tính đến cuối tháng 1 năm 2026, vẫn chưa hiển thị Apps.
Lưu ý: Khi viết tài liệu này, chúng tôi chưa thể kiểm thử kỹ với Claude Desktop hoặc Claude.ai. Nếu gặp sự cố, vui lòng báo cáo.
Chạy MCP Apps bằng Docker
MCP Apps sử dụng Streamable HTTP. Hãy giữ cổng container được liên kết với loopback và đặt một reverse proxy có xác thực hoặc dịch vụ truy cập nhận biết danh tính ở phía trước trước khi cho phép truy cập từ xa. Việc xác thực Host và Origin giúp bảo vệ khỏi tấn công DNS rebinding; chúng không xác thực người gọi.
1. Xây dựng và chạy container 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. Cấu hình quyền truy cập từ xa có xác thực:
Tạo Cloudflare Tunnel có tên, Tailscale Funnel với các biện pháp kiểm soát truy cập hoặc proxy ngược có xác thực tương đương. Trỏ origin riêng tư của proxy đến
http://127.0.0.1:8001, yêu cầu thông tin xác thực danh tính hoặc dịch vụ cho hostname công khai và chỉ chuyển tiếp các yêu cầu đã xác thực đến origin. Cấu hình MCP client để sử dụng luồng OAuth hoặc các header ủy quyền được nhà cung cấp hỗ trợ.
Trước khi thêm thông tin xác thực ZenML vào container, hãy xác minh rằng yêu cầu chưa xác thực không thể truy cập MCP:
curl -i https://mcp.example.com/mcp
Phản hồi phải là 401, 403 của nhà cung cấp quyền truy cập hoặc chuyển hướng đến trang đăng nhập. Phản hồi JSON-RPC hoặc MCP có nghĩa là lớp bảo vệ đang mở và cần được khắc phục trước.
3. Kết nối client đã xác thực:
{
"servers": {
"ZenML": {
"url": "https://mcp.example.com/mcp",
"type": "http"
}
},
"inputs": []
}
- Yêu cầu AI “mở bảng điều khiển các lần chạy pipeline” hoặc “hiển thị biểu đồ hoạt động chạy”
Lưu ý quan trọng:
- Cần có
ZENML_ACTIVE_PROJECT_ID— nếu không, các công cụ chạy pipeline sẽ thất bại với thông báo "No project is currently set as active" --disable-dns-rebinding-protectionchỉ phù hợp khi proxy đã xác thực xác minh host công khai và cổng container vẫn chỉ liên kết với loopback- Giới hạn API key ZenML ở các quyền mà MCP client cần; dùng
ZENML_MCP_WRITE_POLICY=read_onlycho các client chỉ cần kiểm tra
Kiểm thử & Đảm bảo chất lượng
Dự án này có kiểm thử tự động để đảm bảo MCP server luôn hoạt động:
- 🔄 Kiểm thử khói tự động: Một bài kiểm thử khói toàn diện chạy 3 ngày một lần qua GitHub Actions
- 🚨 Tạo issue: Các bài kiểm thử thất bại sẽ tự động tạo GitHub issue kèm thông tin gỡ lỗi chi tiết
- ⚡ CI nhanh: Sử dụng UV cùng bộ nhớ đệm để cài đặt dependency và kiểm thử nhanh chóng
- 🧪 Kiểm thử thủ công: Bạn có thể chạy kiểm thử khói cục bộ bằng
uv run scripts/test_mcp_server.py server/zenml_server.py
Các bài kiểm thử tự động xác minh:
- Kết nối và bắt tay giao thức MCP
- Khởi tạo server và khám phá công cụ
- Chức năng cơ bản của công cụ (khi ZenML server có thể truy cập)
- Liệt kê tài nguyên và prompt
diagnose_zenml_setuptrả về thông tin chẩn đoán có cấu trúc ngay cả trong môi trường bị giới hạn
CI không cần thông tin xác thực kiểm thử mọi adapter thông qua giao thức MCP. CI cho PR và bản phát hành cũng khởi chạy một ZenML 0.97.0 OSS server mới trên địa chỉ loopback, rồi chạy các biên nhận CRUD đã lưu và kiểm tra cô lập dự án cùng tên. Server sử dụng cấu hình và cơ sở dữ liệu tạm thời, được xóa khi job kết thúc; không cần môi trường của repository, self-hosted runner hay thông tin xác thực ZenML.
ZenML OSS server cục bộ tắt xác thực và SQL store không hỗ trợ phát lại pipeline hoặc hạ tầng triển khai bên ngoài. Vì vậy, các biên nhận về quyền truy cập bị giới hạn và các tính năng trigger, replay, deployment, wait-condition và resource-request vẫn là các cổng tùy chọn riêng biệt. Chúng yêu cầu ZENML_MCP_RESTRICTED_INTEGRATION=1 cùng với
ZENML_MCP_RESTRICTED_API_KEY, hoặc ZENML_MCP_ACTION_INTEGRATION=1 cùng với các UUID fixture dùng một lần chính xác trong ZENML_MCP_ACTION_FIXTURE, tương ứng. Bỏ qua do cổng kiểm thử chưa được bật không phải là bằng chứng các khả năng đó đã vượt qua kiểm thử. Người vận hành có thể đặt
ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 để biến việc thiếu cổng tùy chọn thành lỗi. Việc cấp phát hạ tầng đám mây không bao giờ thuộc lượt chạy kiểm thử mặc định.
Gỡ lỗi bằng MCP Inspector
Để gỡ lỗi tương tác, hãy dùng MCP Inspector — công cụ trên web cho phép bạn kiểm thử các công cụ MCP theo thời gian thực:
# 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
Thao tác này mở giao diện web với thông tin xác thực đã được điền sẵn — chỉ cần nhấp Connect rồi dùng thẻ Tools để kiểm thử tương tác bất kỳ công cụ nào.
Xem CLAUDE.md để biết hướng dẫn gỡ lỗi chi tiết hơn.
Quyền riêng tư & Phân tích
ZenML MCP Server thu thập dữ liệu phân tích sử dụng ẩn danh để giúp chúng tôi cải thiện sản phẩm.
Chúng tôi theo dõi:
- Những công cụ nào được sử dụng và tần suất sử dụng
- Tỷ lệ và loại lỗi (chỉ loại lỗi, không có thông báo)
- Thông tin môi trường cơ bản (OS, phiên bản Python và việc chạy trong Docker/CI hay không)
- Thời lượng phiên và kiểu sử dụng công cụ
Chúng tôi KHÔNG thu thập:
- URL ZenML server hoặc API key của bạn
- Tên pipeline, tên model hoặc bất kỳ dữ liệu kinh doanh nào
- Thông báo lỗi hoặc stack trace
- Bất kỳ thông tin nhận dạng cá nhân nào
Để tắt phân tích:
# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false
# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true
Để gỡ lỗi/kiểm thử (ghi sự kiện vào stderr thay vì gửi đi):
export ZENML_MCP_ANALYTICS_DEV=true
Dành cho người dùng Docker: Bạn có thể đặt ZENML_MCP_ANALYTICS_ID (phải là UUID hợp lệ) để duy trì ID ẩn danh nhất quán qua các lần khởi động lại container. Nếu không đặt biến này và hệ thống tệp của container không thể lưu tệp ID phân tích, server sẽ dùng UUID ẩn danh xác định được, tạo từ hash của ZENML_STORE_URL (bản thân URL không bao giờ được gửi dưới dạng thuộc tính sự kiện).
Các tùy chọn phân tích bổ sung:
ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S— thời gian tối đa (giây) để gửi đồng bộ dữ liệu phân tích khi tắt (mặc định: 1.0)
Lưu ý về theo dõi khi tắt: Sự kiện tắt được gửi đồng bộ với thời gian chờ giới hạn để tăng độ tin cậy khi gửi. Tuy nhiên, nếu container bị dừng bằng SIGKILL (ví dụ: docker kill), các trình xử lý khi tắt không thể chạy — đây là giới hạn của Docker/OS, không phải lỗi.
Xác thực khi khởi động
Bạn có thể bật kiểm tra chẩn đoán nhẹ khi khởi động:
# 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
Bạn cũng có thể đặt tùy chọn này qua biến môi trường: ZENML_MCP_STARTUP_VALIDATION=warn.
Công cụ diagnose_zenml_setup cũng có sẵn dưới dạng MCP tool để khắc phục sự cố khi chạy — công cụ này vẫn hoạt động ngay cả khi chưa cài ZenML SDK hoặc thiếu biến môi trường.
Thiết lập thủ công
Điều kiện tiên quyết
Bạn cần có quyền truy cập vào một ZenML server đã triển khai. Nếu chưa có, bạn có thể đăng ký dùng thử miễn phí tại ZenML Pro và chúng tôi sẽ quản lý việc triển khai cho bạn.
Mẹo: Sau khi có ZenML server, hãy xem trang MCP Settings trong dashboard để thiết lập dễ dàng nhất.
Khả năng tương thích: Phiên bản hiện tại đã được kiểm thử với ZenML 0.97.0. Nếu đang chạy phiên bản ZenML cũ hơn, vui lòng dùng bản phát hành trước của MCP server này.
Bạn cũng có thể sẽ cần cài đặt uv trên máy cục bộ. Để biết thêm thông tin, hãy xem
tài liệu uv.
Chúng tôi khuyên bạn nên cài đặt bằng script cài đặt của họ hoặc bằng brew nếu dùng
Mac. (Về mặt kỹ thuật, bạn không cần công cụ này, nhưng nó giúp việc cài đặt và thiết lập dễ dàng hơn.)
Bạn cũng cần clone repository này vào một vị trí nào đó trên máy cục bộ:
git clone https://github.com/zenml-io/mcp-zenml.git
Tệp cấu hình MCP
Tệp cấu hình MCP là tệp JSON cho MCP client biết cách kết nối với MCP server. Các MCP client khác nhau sẽ sử dụng hoặc chỉ định tệp này theo những cách khác nhau. Hai MCP client thường được dùng là Claude Desktop và Cursor, chúng tôi cung cấp hướng dẫn cài đặt bên dưới.
Bạn cần chỉ định ZenML MCP server theo định dạng sau:
{
"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"
}
}
}
}
Khi cung cấp ZENML_STORE_API_KEY, MCP server giữ thông tin xác thực ZenML trong bộ nhớ và không đọc hoặc cập nhật thông tin xác thực được lưu bởi zenml login. Điều này áp dụng cho các lần chạy Python trực tiếp, tiện ích mở rộng MCPB và Docker. Các kết nối không có API key vẫn có thể dùng phiên đăng nhập terminal đã lưu. Hãy khởi động lại MCP server sau khi thay đổi API key; chỉ mở một cuộc trò chuyện mới có thể vẫn dùng lại tiến trình server đang chạy.
Có bốn giá trị giả cần thay thế:
- đường dẫn đến
uvđã cài đặt cục bộ (đường dẫn ở trên là vị trí trên Mac nếu bạn cài bằngbrew) - đường dẫn đến tệp
zenml_server.py(đây là tệp sẽ được chạy khi bạn kết nối với MCP server). Tệp này nằm ở thư mục gốc của repository. Bạn cần chỉ định đường dẫn đầy đủ chính xác đến tệp này. - URL ZenML server (đây là URL của ZenML server. Bạn có thể tìm thấy URL này
trong ZenML Cloud UI). URL sẽ có dạng như
https://d534d987a-zenml.cloudinfra.zenml.io. - API key của ZenML server (đây là API key cho ZenML server. Bạn có thể tìm thấy key này trong ZenML Cloud UI hoặc đọc các tài liệu này để biết cách tạo key. Với ZenML MCP server, chúng tôi khuyên bạn nên dùng tài khoản dịch vụ.)
Bạn có thể thay đổi cách chạy tệp Python của MCP server, nhưng dùng
uv có lẽ là lựa chọn dễ nhất vì công cụ này tự xử lý môi trường và
cài đặt dependency.
Cài đặt để sử dụng với Claude Desktop
Lựa chọn nhanh: Dùng trang MCP Settings trong dashboard ZenML (Settings → MCP) để nhận hướng dẫn cài đặt được cấu hình sẵn và liên kết sâu cho Claude Desktop.
Bạn cần cài phiên bản mới nhất của Claude Desktop.
Bạn chỉ cần mở menu Settings rồi kéo tệp mcp-zenml.mcpb từ
thư mục gốc của repository vào menu; tệp sẽ hướng dẫn bạn qua quy trình
cài đặt và thiết lập. Bạn cần thêm URL ZenML server và API key.
Lưu ý: MCP bundle (.mcpb) thay thế định dạng Desktop Extensions (.dxt) cũ; các tệp .dxt hiện có vẫn hoạt động trong Claude Desktop.
Tùy chọn: Cải thiện cách hiển thị kết quả công cụ ZenML
Để có trải nghiệm tốt hơn với kết quả từ công cụ ZenML, bạn có thể cấu hình Claude hiển thị phản hồi JSON theo định dạng dễ đọc hơn. Trong Claude Desktop, vào Settings → Profile, rồi trong mục "What personal preferences should Claude consider in responses?" hãy thêm nội dung tương tự như sau (hoặc dùng nguyên văn nội dung này!):
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!
Thao tác này sẽ khuyến khích Claude định dạng đầu ra của công cụ ZenML thành bảng markdown, giúp thông tin dễ đọc và dễ hiểu hơn nhiều.
Cài đặt để sử dụng với Cursor
Lựa chọn nhanh: Trang MCP Settings trong dashboard ZenML (Settings → MCP) có thể tạo nội dung
mcp.jsonchính xác với thông tin xác thực được điền sẵn.
Bạn cần cài đặt Cursor.
Cursor hoạt động hơi khác Claude Desktop ở chỗ bạn chỉ định tệp cấu hình theo từng repository. Điều này có nghĩa là nếu muốn dùng ZenML MCP server trong nhiều repository, bạn cần chỉ định tệp cấu hình trong từng repository.
Để thiết lập cho một repository, bạn cần:
- tạo thư mục
.cursorở thư mục gốc của repository - tạo tệp
mcp.jsonbên trong thư mục đó với nội dung ở trên - vào phần cài đặt Cursor và nhấp vào ZenML server để 'enable' server.
Theo kinh nghiệm của chúng tôi, đôi khi chỉ báo lỗi màu đỏ vẫn xuất hiện dù server đang hoạt động. Bạn có thể thử bằng cách trò chuyện trong cửa sổ chat của Cursor. Cursor sẽ cho bạn biết liệu nó có thể truy cập các công cụ ZenML hay không.
Docker Image
Bạn có thể chạy server dưới dạng Docker container. Tiến trình giao tiếp qua stdio nên sẽ chờ kết nối từ MCP client. Truyền thông tin xác thực ZenML qua các biến môi trường.
Image dựng sẵn (Docker Hub)
Tải image đa kiến trúc mới nhất:
docker pull zenmldocker/mcp-zenml:latest
Các bản phát hành có phiên bản được gắn thẻ là X.Y.Z:
docker pull zenmldocker/mcp-zenml:2.0.0
Chạy với thông tin xác thực ZenML của bạn (chế độ 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
Cấu hình MCP chuẩn dùng Docker
{
"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"
]
}
}
}
Tự dựng
Từ thư mục gốc của repository:
docker build -t zenmldocker/mcp-zenml:local .
Chạy image vừa dựng cục bộ:
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 Bundle (.mcpb)
Dự án này sử dụng MCP Bundle (.mcpb) — phiên bản kế nhiệm Desktop Extensions (DXT) của Anthropic. MCP Bundle đóng gói toàn bộ MCP server (bao gồm dependency) vào một tệp duy nhất với cấu hình thân thiện với người dùng.
Lưu ý về việc đổi tên: MCP Bundle thay thế định dạng .dxt cũ. Claude Desktop vẫn tương thích ngược với các tệp .dxt hiện có, nhưng hiện chúng tôi phát hành mcp-zenml.mcpb và khuyên bạn nên dùng định dạng này từ nay về sau.
Tệp mcp-zenml.mcpb trong thư mục gốc của repository sử dụng runtime UV MCPB 0.4.
Host cài đặt các dependency Python đã ghim phiên bản cho hệ điều hành hiện tại,
vì vậy cùng một bundle hoạt động trên macOS, Windows và Linux mà không cần nhúng
các phần mở rộng native dành riêng cho từng nền tảng. Lần đầu UV phân giải môi trường
được đóng gói, quá trình cài đặt cần có kết nối mạng.
Các bản dựng bundle sử dụng lại mcpb-uv.lock đã được commit và phân giải đồ thị phụ thuộc Python của nó ở chế độ ngoại tuyến. Danh sách phụ thuộc của bundle lấy từ
[project].dependencies trong pyproject.toml. Sau khi thay đổi danh sách đó, hãy đặt
MCPB_REFRESH_LOCK=1 để phân giải lại trực tuyến trong khi giữ nguyên mọi phiên bản đã ghim vẫn đáp ứng yêu cầu; MCPB_REFRESH_LOCK=upgrade sẽ chuyển mọi phiên bản đã ghim sang phiên bản mới nhất.
Khi bạn kéo và thả tệp .mcpb vào phần cài đặt của Claude Desktop, ứng dụng sẽ tự động xử lý:
- Cài đặt các phụ thuộc thời gian chạy
- Quản lý cấu hình an toàn
- Khả năng tương thích đa nền tảng
- Quy trình thiết lập thân thiện với người dùng
Để biết thêm thông tin, hãy xem thông báo của Anthropic về Desktop Extensions (DXT) và hướng dẫn liên quan về đóng gói MCP bundle trong tài liệu của họ: https://www.anthropic.com/engineering/desktop-extensions
Được xuất bản trên Anthropic MCP Registry
Máy chủ MCP này được xuất bản lên Anthropic MCP Registry chính thức và có thể được các host tương thích tìm thấy. Với mỗi bản phát hành được gắn thẻ, CI của chúng tôi cập nhật mục đăng ký thông qua CLI mcp-publisher của registry bằng GitHub OIDC, để bạn có thể cài đặt hoặc tìm ZenML MCP Server trực tiếp ở bất cứ nơi nào hỗ trợ registry (ví dụ: danh mục Extensions của Claude Desktop).
- Luôn cập nhật: mục đăng ký được làm mới sau mỗi bản phát hành, dựa trên
manifest.jsonvàserver.jsoncủa commit được gắn thẻ. - Các cách cài đặt thay thế: bạn vẫn có thể cài đặt cục bộ bằng bundle
.mcpbđã đóng gói (xem ở trên) hoặc chạy Docker image.
Tìm hiểu thêm về registry tại đây:
- Anthropic MCP Registry (kho lưu trữ cộng đồng): https://github.com/modelcontextprotocol/registry