ZenML

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ở chuẩn hóa cách các ứng dụng cung cấp ngữ cảnh cho các Mô hình Ngôn ngữ Lớn (LLM). Nó hoạt động như một "cổng USB-C cho các ứng dụng AI" - cung cấp một cách chuẩn hóa để kết nối các mô hình AI với các nguồn dữ liệu và công cụ khác nhau.

MCP tuân theo kiến trúc máy chủ-máy khách trong đó:

• MCP Hosts: Các chương trình như Claude Desktop hoặc IDE muốn truy cập dữ liệu thông qua MCP
• MCP Clients: Các máy khách giao thức duy trì kết nối 1:1 với máy chủ
• MCP Servers: Các chương trình nhẹ phơi bày các khả năng cụ thể thông qua giao thức chuẩn hóa
• Nguồn dữ liệu cục bộ: Các 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ó sẵn qua internet mà máy chủ MCP có thể kết nối tới

ZenML là gì?

ZenML là một nền tảng mã nguồn mở để xây dựng và quản lý các pipeline ML và AI. Nó cung cấp một 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 chức năng đọc cốt lõi từ máy chủ ZenML, cung cấp một cách để lấy thông tin trực tiếp về:

Các thực thể cốt lõi

• Người dùng - tài khoản người dùng và quyền hạn
• Stacks - cấu hình hạ tầng
• Stack Components - các khối xây dựng stack riêng lẻ
• Flavors - các loại thành phần có sẵn
• Service Connectors - xác thực đám mây

Thực thi Pipeline

• Pipelines - định nghĩa pipeline
• Pipeline Runs - lịch sử thực thi và trạng thái
• Pipeline Steps - chi tiết bước riêng lẻ, mã và nhật ký
• Schedules - lịch chạy tự động
• Artifacts - siêu dữ liệu về các artifact dữ liệu (không phải dữ liệu)

Triển khai & Phục vụ

• Snapshots - cấu hình pipeline đóng băng (artifact "chạy/phục vụ cái gì")
• Deployments - các phiên bản phục vụ thời gian chạy với trạng thái, URL và nhật ký
• Services - các điểm cuối phục vụ mô hình

Tổ chức & Khám phá

• Projects - các vùng chứa tổ chức cho tài nguyên ZenML
• Tags - nhãn siêu dữ liệu xuyên suốt để khám phá
• Builds - các artifact build pipeline với thông tin hình ảnh và mã

Mô hình

• Models - các mục đăng ký mô hình ML
• Model Versions - các artifact mô hình có phiên bản

API tương thích (khuyến nghị di chuyển)

• Pipeline run templates vẫn có sẵn trong ZenML 0.97.0, trong khi Snapshots được ưu tiên cho các quy trình làm việc 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 pipeline run mới bằng snapshots (ưu tiên) hoặc tham số kích hoạt dựa trên template đã không còn được dùng.

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 của chúng tôi để chia sẻ trải nghiệm của bạn và giúp chúng tôi làm cho nó tốt hơn nữa!

Hồ sơ công cụ và chính sách ghi

Hồ sơ compact mặc định quảng cáo 16 công cụ. Bảy công cụ chung bao phủ 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 và phân trang đã xác thực
zenml_get_resource	Lấy một tài nguyên, với phạm vi cha và dự án khi cần
zenml_create_resource	Tạo một 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 chính xác
zenml_delete_resource	Xóa hoặc lưu trữ một UUID tài nguyên chính xác
zenml_action_resource	Chạy một hành động vòng đời hoặc quan hệ trong danh sách cho phép mà không thử lại

Chín công cụ tập trung vẫn được giữ lại vì chúng cung cấp chẩn đoán, ngữ cảnh hoạt động, nhật ký hoặc mã được truyền trực tuyến, thực thi pipeline hoặc một App tương tác:

• diagnose_zenml_setup
• get_active_user và get_active_project
• trigger_pipeline
• get_step_logs, get_step_code và get_deployment_logs
• open_pipeline_run_dashboard và open_run_activity_chart

get_step_logs trả về tối đa 50.000 mục, cũ nhất trước, với cờ possibly_truncated, cùng với note cho biết mục nào bị thiếu và tại sao. Truyền tail để chỉ lấy các mục mới nhất. Trên máy chủ ZenML 0.97+, nó phân trang qua kho nhật ký; trên 0.96, nó sử dụng điểm cuối yêu cầu đơn cũ hơn.

Sử 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. Điều này giữ lại lớp tương thích tên công cụ và lược đồ đã được đặc trưng hóa cho ZenML 0.97.0. Nó không thêm hỗ trợ cho các phiên bản máy chủ ZenML cũ hơn. Chỉ sử dụng nó trong khi di chuyển: các hình dạng phản hồi kế thừa có thể phơi bày nhiều siêu dữ liệu vận hành hơn các công cụ gọn nhẹ, mặc dù máy chủ bỏ qua 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ơ.

Đăng ký và quyền ghi là độc lập:

Hồ sơ	Chính sách	Công cụ được quảng cáo
compact	read_write	16
compact	read_only	11
legacy	read_write	57
legacy	read_only	52

Đặt ZENML_MCP_WRITE_POLICY=read_only để xóa tất cả bốn công cụ thay đổi chung và trigger_pipeline khỏi khám phá và điều phối MCP. 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 ZENML_MCP_READ_ONLY=true cũ hơn vẫn được chấp nhận; các giá trị chính sách không hợp lệ thất bại đóng sang chế độ chỉ đọc. Một ZENML_MCP_PROFILE không hợp lệ sẽ dừng khởi động 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à là một thay đổi khám phá phá vỡ cho 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 mỗi lệnh gọi sang các công cụ tài nguyên chung.

Kết quả thay đổi phân biệt các kết quả completed, accepted và unknown. Máy chủ không thử lại một thay đổi sau khi nó có thể đã đến ZenML. Đối với kết quả được chấp nhận hoặc không xác định, hãy làm theo hướng dẫn đối chiếu trong phản hồi trước khi quyết định có gọi lại hay không. Sử dụng thao tác đọc có tên khi có sẵn. Việc tạo webhook và xoay vòng bí mật có thể trả về một bí mật ký mới một lần; các lần đọc sau bỏ qua nó. Các lược đồ xóa nêu rõ một thao tác có lưu trữ siêu dữ liệu, xóa siêu dữ liệu, hủy cung cấp một tài nguyên trực tiếp hay có thể xóa dữ liệu artifact đã lưu trữ hay không.

Bản phát hành 2.0 đầu tiên bao gồm các thao tác thông thường cho projects, stacks và components, flavors, services, pipelines và runs, snapshots và templates, deployments, artifacts và versions, models và versions, tags, connectors, code repositories, webhooks, triggers, wait conditions và hook invocations. Users, schedules, service connector types, secrets và resource requests có phạm vi chỉ đọc được hiển thị bởi zenml_describe_resources. Nó loại trừ 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ị bí mật, đăng nhập và xác minh connector, sự kiện webhook thô và các công cụ gỡ lỗi hoặc lineage tổng hợp.

Bắt đầu một quy trình làm việc chung bằng cách khám phá lược đồ chính xác, sau đó gọi nó:

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

Prompts và resources vẫn có sẵn trong cả hai hồ sơ. Các prompt phân tích, các điểm cuối lược đồ tài nguyên có giới hạn và most_recent_runs là các prompt hoặc resources MCP thay vì các công cụ.

Tương thích run-template

ZenML 0.97.0 giữ lại các API CRUD run-template. Snapshots được ưu tiên cho các quy trình làm việc mới. Việc tạo pipeline thuận tiện và tham số kích hoạt dựa trên template đã không còn được dùng. Trong hồ sơ kế thừa, get_run_template và list_run_templates vẫn có sẵn cho các máy khách hiện có.

Đầu vào tag kế thừa 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 phía máy chủ tương đương. Một giá trị không rỗng sẽ bị từ chối trước lệnh gọi SDK. Lọc thẻ snapshot vẫn có sẵn.

Di chuyển: Run Templates → Snapshots

Tại sao thay đổi? Snapshots đã thay thế run templates như artifact pipeline chạy được ưu tiên của ZenML. SDK 0.97.0 vẫn hỗ trợ CRUD run-template, trong khi mã mới nên sử dụng snapshots.

Hướng dẫn di chuyển nhanh

Mẫu kế thừa (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=...)

Ví dụ quy trình làm việc (Snapshot-First)

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)

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 tích hợp deployer thích hợp phải được cài đặt.

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 trong dashboard ZenML của bạn.

Điều hướng đến Settings → MCP trong dashboard ZenML của bạn để nhận:

• Các đoạn mã được cấu hình sẵn cho URL máy chủ và thông tin xác thực cụ thể của bạn
• Cài đặt một cú nhấp chuột qua các deep link cho các IDE được hỗ trợ
• Cấu hình sao chép-dán cho VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex và hơn thế nữa
• Các tùy chọn Docker và uv dựa trên 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ỉ với một cú nhấp chuột. Token được tự động bao gồm trong tất cả các đoạn mã cấu hình được tạo.

Người dùng ZenML OSS

1. Đầu tiên tạo một service account token qua Settings → Service Accounts
2. Dán token vào trang MCP Settings
3. Sao chép cấu hình đã tạo cho IDE của bạn

---

Thích thiết lập thủ công? Xem các hướng dẫn chi tiết bên dưới.

MCP Apps (Thử nghiệm)

MCP Apps là gì? MCP Apps là các giao diện HTML tương tác mà máy chủ MCP có thể phục vụ trực tiếp vào các máy khách AI. Chúng hiển thị trong các iframe sandbox và có thể gọi các công cụ máy chủ theo hai chiều. Xem thông báo chính thức để biết chi tiết đầy đủ.

Máy chủ này bao gồm hai MCP Apps thử nghiệm:

App	Công cụ	Mô tả
Pipeline Runs Dashboard	open_pipeline_run_dashboard	Bảng tương tác về các pipeline run gần đây với trạng thái, chi tiết bước và nhật ký
Run Activity Chart	open_run_activity_chart	Biểu đồ cột về hoạt động pipeline run trong 30 ngày qua với phân tích trạng thái

Các app này được bao gồm như các ví dụ chứng minh khái niệm. Chúng tôi hoan nghênh phản hồi và đóng góp cho nhiều MCP Apps hơn. Tính năng mới này vẫn còn ở giai đoạn đầu nên chúng tôi sẽ phải xem nó phát triển như thế nào. Chúng tôi mong đợi sẽ hỗ trợ nó đầy đủ hơn trong tương lai.

Các máy khách được hỗ trợ

MCP Apps yêu cầu 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 (Phiên bản Insiders)
• ✅ Goose
• ✅ ChatGPT (sắp ra mắt)
• ⚠️ Claude Desktop -- tính đến cuối tháng 1 năm 2026, chưa hiển thị Apps.
• ⚠️ Claude.ai (web) — tính đến cuối tháng 1 năm 2026, chưa hiển thị Apps.

Lưu ý: Chúng tôi không thể kiểm tra kỹ lưỡng với Claude Desktop hoặc Claude.ai tại thời điểm viết. Nếu bạn gặp sự cố, vui lòng báo cáo chúng.

Chạy MCP Apps với Docker

MCP Apps sử dụng Streamable HTTP. Giữ cổng container ràng buộc 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 nó trước khi cho phép truy cập từ xa. Xác thực Host và Origin bảo vệ chống lại 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 truy cập từ xa được xác thực: Tạo một Cloudflare Tunnel có tên, Tailscale Funnel với kiểm soát truy cập, hoặc một reverse proxy xác thực tương đương. Trỏ origin riêng tư của nó tới http://127.0.0.1:8001, yêu cầu danh tính hoặc thông tin xác thực dịch vụ cho hostname công khai, và chỉ chuyển các yêu cầu đã xác thực tới origin. Cấu hình MCP client của bạn để sử dụng luồng OAuth được hỗ trợ của nhà cung cấp hoặc các header ủy quyền.

Trước khi thêm thông tin xác thực ZenML vào container, hãy xác minh rằng một 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 truy cập, hoặc chuyển hướng đăng nhập. Phản hồi JSON-RPC hoặc MCP có nghĩa là vùng ngoại vi đang mở và phải được sửa trước.

3. Kết nối client đã xác thực của bạn:

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

• Yêu cầu AI "mở bảng điều khiển pipeline runs" hoặc "hiển thị biểu đồ hoạt động run"

Lưu ý quan trọng:

• ZENML_ACTIVE_PROJECT_ID là bắt buộc — nếu không có nó, các công cụ pipeline run sẽ thất bại với thông báo "No project is currently set as active"
• --disable-dns-rebinding-protection chỉ phù hợp khi proxy đã xác thực xác thực host công khai và cổng container vẫn chỉ ở chế độ loopback
• Giới hạn khóa API ZenML ở các quyền mà MCP client cần; sử dụng ZENML_MCP_WRITE_POLICY=read_only cho các client chỉ xem

Kiểm thử & Đảm bảo chất lượng

Dự án này bao gồm 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 mỗi 3 ngày qua GitHub Actions
• 🚨 Tạo issue tự động: Các bài kiểm thử thất bại tự động tạo issue GitHub với thông tin gỡ lỗi chi tiết
• ⚡ CI nhanh: Sử dụng UV với bộ nhớ đệm để cài đặt phụ thuộc và kiểm thử nhanh
• 🧪 Kiểm thử thủ công: Bạn có thể chạy bài 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 giao thức MCP và bắt tay
• Khởi tạo server và khám phá công cụ
• Chức năng công cụ cơ bản (khi ZenML server có thể truy cập)
• Liệt kê tài nguyên và prompt
• diagnose_zenml_setup trả về chẩn đoán có cấu trúc ngay cả trong môi trường hạn chế

CI không cần thông tin xác thực bao phủ mọi adapter thông qua giao thức MCP. CI cho PR và bản phát hành cũng khởi động một ZenML 0.97.0 OSS server mới trên địa chỉ loopback và chạy các receipt CRUD bền vững và 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 thoát; không yêu cầu môi trường repository, runner tự lưu trữ, hoặc thông tin xác thực ZenML.

ZenML local OSS server vô hiệu hóa xác thực và kho lưu trữ SQL của nó không hỗ trợ phát lại pipeline hoặc cơ sở hạ tầng triển khai bên ngoài. Do đó, các receipt truy cập hạn chế và kích hoạt tính năng, phát lại, triển khai, điều kiện chờ và yêu cầu tài nguyên vẫn là các cổng chọn tham gia riêng biệt. Chúng yêu cầu ZENML_MCP_RESTRICTED_INTEGRATION=1 với ZENML_MCP_RESTRICTED_API_KEY, hoặc ZENML_MCP_ACTION_INTEGRATION=1 với các UUID fixture dùng một lần chính xác trong ZENML_MCP_ACTION_FIXTURE, tương ứng. Một lần bỏ qua có cổng không phải là bằng chứng rằng các khả năng đó đã vượt qua. Người vận hành có thể đặt ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 để biến một cổng chọn tham gia bị thiếu thành lỗi. Việc cung cấp cơ sở hạ tầng đám mây không bao giờ là một phần của lần chạy kiểm thử mặc định.

Gỡ lỗi với MCP Inspector

Để gỡ lỗi tương tác, hãy sử dụng MCP Inspector — một công cụ dựa trên web cho phép bạn kiểm tra các công cụ MCP trong 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ở một giao diện web với thông tin xác thực của bạn được điền sẵn — chỉ cần nhấp vào Connect và sử dụng tab Tools để kiểm tra bất kỳ công cụ nào một cách tương tác.

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 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:

• Công cụ nào được sử dụng và tần suất
• 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 (hệ điều hành, phiên bản Python và có đang chạy trong Docker/CI hay không)
• Thời lượng phiên và mẫu sử dụng công cụ

Chúng tôi KHÔNG thu thập:

• URL server ZenML hoặc khóa API của bạn
• Tên pipeline, tên mô hình hoặc bất kỳ dữ liệu kinh doanh nào
• Thông báo lỗi hoặc dấu vết ngăn xếp
• 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 lại sự kiện vào stderr thay vì gửi):

export ZENML_MCP_ANALYTICS_DEV=true

Đối với 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 giữa các lần khởi động lại container. Nếu bạn không đặt nó và hệ thống tệp container không thể lưu trữ tệp ID phân tích, server sẽ dự phòng sang một UUID ẩn danh xác định được tạo từ hàm băm 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) để xả phân tích đồng bộ trong khi tắt máy (mặc định: 1.0)

Lưu ý về theo dõi tắt máy: Các sự kiện tắt máy được gửi đồng bộ với thời gian chờ có giới hạn để đảm bảo độ tin cậy gửi tốt nhất. Tuy nhiên, nếu một container bị giết bằng SIGKILL (ví dụ: docker kill), các trình xử lý tắt máy không thể kích hoạt — đây là giới hạn của Docker/OS, không phải lỗi.

Xác thực khởi động

Bạn có thể bật kiểm tra chẩn đoán khởi động nhẹ:

# 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 điều 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 công cụ MCP để khắc phục sự cố thời gian chạy — nó hoạt động ngay cả khi ZenML SDK không được cài đặt 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 sẽ cần quyền truy cập vào một ZenML server đã triển khai. Nếu bạn 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: Khi bạn đã có ZenML server, hãy xem trang Cài đặt MCP trong bảng điều khiển của bạn để có trải nghiệm thiết lập dễ dàng nhất.

Tương thích: Phiên bản hiện tại được kiểm thử với ZenML 0.97.0. Nếu bạn đang chạy phiên bản ZenML cũ hơn, vui lòng sử dụng bản phát hành trước đó của MCP server này.

Bạn cũng sẽ (có thể) cần cài đặt uv 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 qua tập lệnh cài đặt của họ hoặc qua brew nếu sử dụng Mac. (Về mặt kỹ thuật bạn không cần nó, nhưng nó giúp việc cài đặt và thiết lập dễ dàng.)

Bạn cũng sẽ cần sao chép repository này ở đâu đó cục bộ:

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

Tệp cấu hình MCP của bạn

Tệp cấu hình MCP là một tệp JSON cho MCP client biết cách kết nối với MCP server của bạn. Các MCP client khác nhau sẽ sử dụng hoặc chỉ định điều này khác nhau. Hai MCP client thường được sử dụng là Claude Desktop và Cursor, mà chúng tôi cung cấp hướng dẫn cài đặt bên dưới.

Bạn sẽ cần chỉ định ZenML MCP server của mình 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"
            }
        }
    }
}

Có bốn giá trị giả mà bạn sẽ cần thay thế:

• đường dẫn đến uv được cài đặt cục bộ của bạn (đường dẫn được liệt kê ở trên là nơi nó sẽ nằm trên Mac nếu bạn cài đặt qua brew)
• đườ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 bên trong repository này tại thư mục gốc. Bạn sẽ cần chỉ định đường dẫn đầy đủ chính xác đến tệp này.
• URL server ZenML (đây là URL của ZenML server của bạn. Bạn có thể tìm thấy URL này trong ZenML Cloud UI). Nó sẽ trông giống như https://d534d987a-zenml.cloudinfra.zenml.io.
• khóa API server ZenML (đây là khóa API cho ZenML server của bạn. Bạn có thể tìm thấy khóa này trong ZenML Cloud UI hoặc đọc các tài liệu này về cách tạo một khóa. Đối với mục đích của ZenML MCP server, chúng tôi khuyên bạn nên sử dụng tài khoản dịch vụ.)

Bạn có thể tự do thay đổi cách chạy tệp Python MCP server, nhưng sử dụng uv có lẽ sẽ là tùy chọn dễ nhất vì nó xử lý môi trường và cài đặt phụ thuộc cho bạn.

Cài đặt để sử dụng với Claude Desktop

Thay thế nhanh: Sử dụng trang Cài đặt MCP trong bảng điều khiển ZenML của bạn (Cài đặt → 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 sẽ cần cài đặt phiên bản mới nhất của Claude Desktop.

Bạn có thể chỉ cần mở menu Cài đặt và kéo tệp mcp-zenml.mcpb từ thư mục gốc của repository này vào menu và nó sẽ hướng dẫn bạn qua quá trình cài đặt và thiết lập. Bạn sẽ cần thêm URL server ZenML và khóa API của mình.

Lưu ý: MCP bundles (.mcpb) thay thế định dạng Desktop Extensions (.dxt) cũ hơn; các tệp .dxt hiện có vẫn hoạt động trong Claude Desktop.

Tùy chọn: Cải thiện hiển thị đầu ra công cụ ZenML

Để có trải nghiệm tốt hơn với kết quả công cụ ZenML, bạn có thể cấu hình Claude để hiển thị các phản hồi JSON ở định dạng dễ đọc hơn. Trong Claude Desktop, đi tới Cài đặt → Hồ sơ và trong phần "What personal preferences should Claude consider in responses?", thêm nội dung như sau (hoặc sử dụng chính xác những từ 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!

Điều này sẽ khuyến khích Claude định dạng đầu ra công cụ ZenML dưới dạng 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

Thay thế nhanh: Trang Cài đặt MCP trong bảng điều khiển ZenML của bạn (Cài đặt → MCP) có thể tạo nội dung mcp.json chính xác với thông tin xác thực được điền sẵn.

Bạn sẽ cần cài đặt Cursor.

Cursor hoạt động hơi khác so với Claude Desktop ở chỗ bạn chỉ định tệp cấu hình trên cơ sở từng repository. Điều này có nghĩa là nếu bạn muốn sử dụng ZenML MCP server trong nhiều repo, bạn sẽ cần chỉ định tệp cấu hình trong mỗi repo đó.

Để thiết lập cho một repository duy nhất, bạn sẽ cần:

• tạo một thư mục .cursor trong thư mục gốc của repository của bạn
• bên trong nó, tạo một tệp mcp.json với nội dung ở trên
• đi vào cài đặt Cursor của bạn và nhấp vào ZenML server để 'bật' nó.

Theo kinh nghiệm của chúng tôi, đôi khi nó hiển thị chỉ báo lỗi màu đỏ ngay cả khi nó đang hoạt động. Bạn có thể thử nó bằng cách trò chuyện trong cửa sổ trò chuyện Cursor. Nó 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 container Docker. Quá trình giao tiếp qua stdio, vì vậy nó sẽ chờ kết nối MCP client. Truyền thông tin xác thực ZenML của bạn qua các biến môi trường.

Hình ảnh dựng sẵn (Docker Hub)

Kéo hình ảnh đa kiến trúc mới nhất:

docker pull zenmldocker/mcp-zenml:latest

Các bản phát hành theo 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 sử 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"
      ]
    }
  }
}

Xây dựng cục bộ

Từ thư mục gốc của repository:

docker build -t zenmldocker/mcp-zenml:local .

Chạy hình ảnh được xây 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 Bundles (.mcpb)

Dự án này sử dụng MCP Bundles (.mcpb) — sự kế thừa của Anthropic's Desktop Extensions (DXT). MCP Bundles đóng gói toàn bộ MCP server (bao gồm cả các phụ thuộc) 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ề đổi tên: MCP Bundles thay thế định dạng .dxt cũ hơn. Claude Desktop vẫn tương thích ngược với các tệp .dxt hiện có, nhưng chúng tôi hiện cung cấp mcp-zenml.mcpb và khuyên bạn nên sử dụng nó từ nay về sau.

Tệp mcp-zenml.mcpb trong thư mục gốc của repository sử dụng MCPB 0.4 UV runtime. Máy chủ cài đặt các phụ thuộc Python được ghim 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 gốc dành riêng cho nền tảng. Cài đặt cần truy cập mạng trong lần đầu tiên UV giải quyết môi trường được đóng gói.

Các bản dựng bundle tái sử dụng mcpb-uv.lock đã cam kết và giải quyết biểu đồ phụ thuộc Python của nó ở chế độ ngoại tuyến. Danh sách phụ thuộc của bundle đến từ [project].dependencies trong pyproject.toml. Sau khi thay đổi danh sách đó, hãy đặt MCPB_REFRESH_LOCK=1 để giải quyết lại trực tuyến trong khi giữ mọi ghim vẫn phù hợp; MCPB_REFRESH_LOCK=upgrade di chuyển mọi ghim đến phiên bản mới nhất của nó.

Khi bạn kéo và thả tệp .mcpb vào cài đặt của Claude Desktop, nó sẽ tự động xử lý:

• Cài đặt các phụ thuộc runtime
• Quản lý cấu hình an toàn
• 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 đóng gói bundle MCP liên quan 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

MCP server này được xuất bản lên Anthropic MCP Registry chính thức và có thể được tìm thấy bởi các host tương thích. Trên mỗi bản phát hành có gắn thẻ (tagged release), CI của chúng tôi cập nhật mục registry thông qua CLI mcp-publisher của registry bằng GitHub OIDC, vì vậy bạn có thể cài đặt hoặc khám phá ZenML MCP Server trực tiếp ở bất kỳ 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 registry được làm mới sau mỗi bản phát hành từ manifest.json và server.json của commit được gắn thẻ.
• Đường cài đặt thay thế: bạn vẫn có thể cài đặt cục bộ qua bundle .mcpb được đóng gói (xem ở trên) hoặc chạy image Docker.

Tìm hiểu thêm về registry tại đây:

• Anthropic MCP Registry (kho cộng đồng): https://github.com/modelcontextprotocol/registry