This project implements a Model Context Protocol (MCP) server for interacting with the ZenML API. The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It acts like a "USB-C port for AI applications" - providing a standardized way to connect AI models to different data sources and tools. MCP follows a client-server
Add this skill
npx mdskills install zenml-io/mcp-zenmlComprehensive MCP server with extensive ZenML API coverage and excellent documentation
1# MCP Server for ZenML2[](https://archestra.ai/mcp-catalog/zenml-io__mcp-zenml)34This project implements a [Model Context Protocol5(MCP)](https://modelcontextprotocol.io/introduction) server for interacting with6the [ZenML](https://zenml.io) API.78910## What is MCP?1112The Model Context Protocol (MCP) is an open protocol that standardizes how13applications provide context to Large Language Models (LLMs). It acts like a14"USB-C port for AI applications" - providing a standardized way to connect AI15models to different data sources and tools.1617MCP follows a client-server architecture where:18- **MCP Hosts**: Programs like Claude Desktop or IDEs that want to access data through MCP19- **MCP Clients**: Protocol clients that maintain 1:1 connections with servers20- **MCP Servers**: Lightweight programs that expose specific capabilities through the standardized protocol21- **Local Data Sources**: Your computer's files, databases, and services that MCP servers can securely access22- **Remote Services**: External systems available over the internet that MCP servers can connect to2324## What is ZenML?2526ZenML is an open-source platform for building and managing ML and AI pipelines.27It provides a unified interface for managing data, models, and experiments.2829For more information, see the [ZenML website](https://zenml.io) and [our documentation](https://docs.zenml.io).3031## Features3233The server provides MCP tools to access core read functionality from the ZenML34server, providing a way to get live information about:3536### Core Entities37- **Users** - user accounts and permissions38- **Stacks** - infrastructure configurations39- **Stack Components** - individual stack building blocks40- **Flavors** - available component types41- **Service Connectors** - cloud authentication4243### Pipeline Execution44- **Pipelines** - pipeline definitions45- **Pipeline Runs** - execution history and status46- **Pipeline Steps** - individual step details, code, and logs47- **Schedules** - automated run schedules48- **Artifacts** - metadata about data artifacts (not the data itself)4950### Deployment & Serving51- **Snapshots** - frozen pipeline configurations (the "what to run/serve" artifact)52- **Deployments** - runtime serving instances with status, URL, and logs53- **Services** - model serving endpoints5455### Organization & Discovery56- **Projects** - organizational containers for ZenML resources57- **Tags** - cross-cutting metadata labels for discovery58- **Builds** - pipeline build artifacts with image and code info5960### Models61- **Models** - ML model registry entries62- **Model Versions** - versioned model artifacts6364### Deprecated (migration recommended)65- ~~Pipeline run templates~~ → use **Snapshots** instead (see [Migration Guide](#migration-run-templates--snapshots))6667The server also allows you to **trigger new pipeline runs** using snapshots (preferred) or run templates (deprecated).6869*Note: We're continuously improving this integration based on user feedback.70Please join our [Slack community](https://zenml.io/slack) to share your experience71and help us make it even better!*7273## Available Tools7475The MCP server exposes the following tools, grouped by category:7677### Pipeline Execution (New in v1.2)78| Tool | Description |79|------|-------------|80| `get_snapshot` | Get a frozen pipeline configuration by name/ID |81| `list_snapshots` | List snapshots with filters (runnable, deployable, deployed, tag) |82| `get_deployment` | Get a deployment's runtime status and URL |83| `list_deployments` | List deployments with filters (status, pipeline, tag) |84| `get_deployment_logs` | Get bounded logs from a deployment (tail=100 default, max 1000) |85| `trigger_pipeline` | Trigger a pipeline run (prefer `snapshot_name_or_id` parameter) |8687### Organization (New in v1.2)88| Tool | Description |89|------|-------------|90| `get_active_project` | Get the currently active project |91| `get_project` | Get project details by name/ID |92| `list_projects` | List all projects |93| `get_tag` | Get tag details (exclusive, colors) |94| `list_tags` | List tags with filters (resource_type) |95| `get_build` | Get build details (image, code embedding) |96| `list_builds` | List builds with filters (is_local, contains_code) |9798### Core Entities99| Tool | Description |100|------|-------------|101| `get_user`, `list_users`, `get_active_user` | User management |102| `get_stack`, `list_stacks` | Stack configurations |103| `get_stack_component`, `list_stack_components` | Stack components |104| `get_flavor`, `list_flavors` | Component flavors |105| `get_service_connector`, `list_service_connectors` | Cloud connectors |106| `get_pipeline_run`, `list_pipeline_runs` | Pipeline runs |107| `get_run_step`, `list_run_steps` | Step details |108| `get_step_logs`, `get_step_code` | Step logs and source code |109| `list_pipelines`, `get_pipeline_details` | Pipeline definitions |110| `get_schedule`, `list_schedules` | Schedules |111| `list_artifacts` | Artifact metadata |112| `list_secrets` | Secret names (not values) |113| `get_service`, `list_services` | Model services |114| `get_model`, `list_models` | Model registry |115| `get_model_version`, `list_model_versions` | Model versions |116117### Interactive Apps (Experimental)118| Tool | Description |119|------|-------------|120| `open_pipeline_run_dashboard` | Open interactive pipeline runs dashboard (MCP App) |121| `open_run_activity_chart` | Open 30-day run activity bar chart (MCP App) |122123### Analysis Tools124| Tool | Description |125|------|-------------|126| `stack_components_analysis` | Analyze stack component usage |127| `recent_runs_analysis` | Analyze recent pipeline runs |128| `most_recent_runs` | Get N most recent runs |129130### Deprecated Tools131| Tool | Replacement |132|------|-------------|133| `get_run_template` | Use `get_snapshot` instead |134| `list_run_templates` | Use `list_snapshots` instead |135| `trigger_pipeline(template_id=...)` | Use `trigger_pipeline(snapshot_name_or_id=...)` |136137## Migration: Run Templates → Snapshots138139**Why the change?** ZenML evolved its "runnable pipeline artifact" concept. Run Templates are now deprecated wrappers that internally just point to Snapshots. New code should use Snapshots directly.140141### Quick Migration Guide142143| Old Pattern (Templates) | New Pattern (Snapshots) |144|------------------------|------------------------|145| `list_run_templates()` | `list_snapshots(runnable=True, named_only=True)` |146| `get_run_template(name)` | `get_snapshot(name, include_config_schema=True)` |147| `trigger_pipeline(template_id=...)` | `trigger_pipeline(snapshot_name_or_id=...)` |148149### Example Workflow (Snapshot-First)150151```1521. Discover project context:153 → get_active_project()1541552. Find runnable snapshots:156 → list_snapshots(runnable=True, named_only=True)1571583. Trigger a run:159 → trigger_pipeline(pipeline_name_or_id="my-pipeline", snapshot_name_or_id="my-snapshot")1601614. Check deployments:162 → list_deployments(status="running")163 → get_deployment_logs(name_id_or_prefix="my-deployment", tail=100)164```165166**Note:** `get_deployment_logs` returns bounded output (default 100 lines, max 1000, capped at 100KB) and requires the appropriate deployer integration to be installed.167168## Quick Setup via Dashboard (Recommended)169170The easiest way to set up the ZenML MCP Server is through your ZenML dashboard's **MCP Settings page**.171172173174Navigate to **Settings → MCP** in your ZenML dashboard to get:175176- **Pre-configured snippets** for your specific server URL and credentials177- **One-click installation** via deep links for supported IDEs178- **Copy-paste configurations** for VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex, and more179- **Docker and uv options** based on your preference180181### ZenML Pro Users182183The MCP Settings page lets you generate a Personal Access Token (PAT) with a single click. The token is automatically included in all generated configuration snippets.184185### ZenML OSS Users1861871. First create a service account token via **Settings → Service Accounts**1882. Paste the token into the MCP Settings page1893. Copy the generated configuration for your IDE190191---192193**Prefer manual setup?** See the detailed instructions below.194195## MCP Apps (Experimental)196197> **What are MCP Apps?** MCP Apps are interactive HTML UIs that MCP servers can198> serve directly into AI clients. They render in sandboxed iframes and can call199> server tools bidirectionally. See the [official announcement](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/)200> for full details.201202203204This server includes two experimental MCP Apps:205206| App | Tool | Description |207|-----|------|-------------|208| **Pipeline Runs Dashboard** | `open_pipeline_run_dashboard` | Interactive table of recent pipeline runs with status, step details, and logs |209| **Run Activity Chart** | `open_run_activity_chart` | Bar chart of pipeline run activity over the last 30 days with status breakdown |210211212213These apps are included as proof-of-concept examples. We welcome feedback and contributions for more MCP Apps. It is still early days for this new feature so we'll have to see how it evolves. We expect to support it more fully in the future.214215### Supported Clients216217MCP Apps require **Streamable HTTP** transport (not stdio). The following clients218currently support MCP Apps:219220- ✅ **VS Code** (Insiders Edition)221- ✅ **Goose**222- ✅ **ChatGPT** (launching soon)223- ⚠️ **Claude Desktop** -- as of late January 2026, doesn't yet render Apps.224- ⚠️ **Claude.ai** (web) — as of late January 2026, doesn't yet render Apps.225226> **Note:** We were unable to test thoroughly with Claude Desktop or Claude.ai at the time of writing. If you encounter issues, please [report them](https://github.com/zenml-io/mcp-zenml/issues).227228### Running MCP Apps with Docker229230MCP Apps require Streamable HTTP transport and a publicly reachable URL (for231cloud-hosted clients like Claude.ai). The simplest setup uses Docker +232Cloudflare tunnel:233234**1. Build and run the Docker container:**235236```bash237docker build -t mcp-zenml:apps .238239docker run --rm -d --name mcp-zenml-apps -p 8001:8001 \240 -e ZENML_STORE_URL="https://your-zenml-server.example.com" \241 -e ZENML_STORE_API_KEY="your-api-key" \242 -e ZENML_ACTIVE_PROJECT_ID="your-project-id" \243 mcp-zenml:apps --transport streamable-http --host 0.0.0.0 --port 8001 \244 --disable-dns-rebinding-protection245```246247**2. Start a Cloudflare tunnel (for cloud clients):**248249```bash250npx cloudflared tunnel --url http://localhost:8001251```252253This prints a public URL like `https://random-words.trycloudflare.com`.254255**3. Connect your client:**256257- In Claude Desktop or other clients, add the MCP server with URL:258 `https://random-words.trycloudflare.com/mcp` e.g.:259260```json261{262 "servers": {263 "ZenML": {264 "url": "https://USE-YOUR-OWN-URL.trycloudflare.com/mcp",265 "type": "http"266 }267 },268 "inputs": []269}270```271272- Ask the AI to "open the pipeline runs dashboard" or "show the run activity chart"273274**Important notes:**275- `ZENML_ACTIVE_PROJECT_ID` is required — without it, pipeline run tools will276 fail with "No project is currently set as active"277- The `--disable-dns-rebinding-protection` flag is needed when running behind278 reverse proxies (cloudflared, ngrok) — it's safe when the proxy handles security279- The tunnel URL changes on each restart — update your client integration accordingly280281## Testing & Quality Assurance282283This project includes automated testing to ensure the MCP server remains functional:284285- **🔄 Automated Smoke Tests**: A comprehensive smoke test runs every 3 days via GitHub Actions286- **🚨 Issue Creation**: Failed tests automatically create GitHub issues with detailed debugging information287- **⚡ Fast CI**: Uses UV with caching for quick dependency installation and testing288- **🧪 Manual Testing**: You can run the smoke test locally using `uv run scripts/test_mcp_server.py server/zenml_server.py`289290The automated tests verify:291- MCP protocol connection and handshake292- Server initialization and tool discovery293- Basic tool functionality (when ZenML server is accessible)294- Resource and prompt enumeration295296## Debugging with MCP Inspector297298For interactive debugging, use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) — a web-based tool that lets you test MCP tools in real-time:299300```bash301# Using .env.local (recommended for development)302cp .env.local.example .env.local # Then edit with your credentials303source .env.local && npx @modelcontextprotocol/inspector \304 -e ZENML_STORE_URL=$ZENML_STORE_URL \305 -e ZENML_STORE_API_KEY=$ZENML_STORE_API_KEY \306 -- uv run server/zenml_server.py307```308309This opens a web UI with your credentials pre-filled — just click **Connect** and use the **Tools** tab to test any tool interactively.310311See [CLAUDE.md](CLAUDE.md#debugging-with-mcp-inspector) for more detailed debugging instructions.312313## Privacy & Analytics314315The ZenML MCP Server collects anonymous usage analytics to help us improve the product.316317**We track:**318- Which tools are used and how often319- Error rates and types (error type only, no messages)320- Basic environment info (OS, Python version, and whether running in Docker/CI)321- Session duration and tool usage patterns322323**We do NOT collect:**324- Your ZenML server URL or API key325- Pipeline names, model names, or any business data326- Error messages or stack traces327- Any personally identifiable information328329**To disable analytics:**330331```bash332# Option 1333export ZENML_MCP_ANALYTICS_ENABLED=false334335# Option 2336export ZENML_MCP_DISABLE_ANALYTICS=true337```338339**For debugging/testing (logs events to stderr instead of sending):**340341```bash342export ZENML_MCP_ANALYTICS_DEV=true343```344345**For Docker users:** Set `ZENML_MCP_ANALYTICS_ID` to maintain a consistent anonymous ID across container restarts.346347## Manual Setup348349### Prerequisites350351You will need to have access to a deployed ZenML server. If you don't have one,352you can sign up for a free trial at [ZenML Pro](https://cloud.zenml.io) and we'll manage the deployment for you.353354> **Tip:** Once you have a ZenML server, check out the [MCP Settings page](#quick-setup-via-dashboard-recommended) in your dashboard for the easiest setup experience.355356> **Compatibility:** This MCP server is tested with and recommended for **ZenML >= 0.93.0**.357> If you are running an older ZenML version, please use an [earlier release](https://github.com/zenml-io/mcp-zenml/releases) of this MCP server.358359You will also (probably) need to have `uv` installed locally. For more information, see360the [`uv` documentation](https://docs.astral.sh/uv/getting-started/installation/).361We recommend installation via their installer script or via `brew` if using a362Mac. (Technically you don't *need* it, but it makes installation and setup easy.)363364You will also need to clone this repository somewhere locally:365366```bash367git clone https://github.com/zenml-io/mcp-zenml.git368```369370### Your MCP config file371372The MCP config file is a JSON file that tells the MCP client how to connect to373your MCP server. Different MCP clients will use or specify this differently. Two374commonly-used MCP clients are [Claude Desktop](https://claude.ai/download) and375[Cursor](https://www.cursor.com/), for which we provide installation instructions376below.377378You will need to specify your ZenML MCP server in the following format:379380```json381{382 "mcpServers": {383 "zenml": {384 "command": "/usr/local/bin/uv",385 "args": ["run", "path/to/server/zenml_server.py"],386 "env": {387 "LOGLEVEL": "WARNING",388 "NO_COLOR": "1",389 "ZENML_LOGGING_COLORS_DISABLED": "true",390 "ZENML_LOGGING_VERBOSITY": "WARN",391 "ZENML_ENABLE_RICH_TRACEBACK": "false",392 "PYTHONUNBUFFERED": "1",393 "PYTHONIOENCODING": "UTF-8",394 "ZENML_STORE_URL": "https://your-zenml-server-goes-here.com",395 "ZENML_STORE_API_KEY": "your-api-key-here"396 }397 }398 }399}400```401402There are four dummy values that you will need to replace:403404- the path to your locally installed `uv` (the path listed above is where it405 would be on a Mac if you installed it via `brew`)406- the path to the `zenml_server.py` file (this is the file that will be run when407 you connect to the MCP server). This file is located inside this repository at408 the root. You will need to specify the exact full path to this file.409- the ZenML server URL (this is the URL of your ZenML server. You can find this410 in the ZenML Cloud UI). It will look something like `https://d534d987a-zenml.cloudinfra.zenml.io`.411- the ZenML server API key (this is the API key for your ZenML server. You can412 find this in the ZenML Cloud UI or [read these413 docs](https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account)414 on how to create one. For the purposes of the ZenML MCP server we recommend415 using a service account.)416417You are free to change the way you run the MCP server Python file, but using418`uv` will probably be the easiest option since it handles the environment and419dependency installation for you.420421422### Installation for use with Claude Desktop423424> **Quick alternative:** Use the MCP Settings page in your ZenML dashboard (Settings → MCP) to get pre-configured installation instructions and deep links for Claude Desktop.425426You will need to have the latest version of [Claude Desktop](https://claude.ai/download) installed.427428You can simply open the Settings menu and drag the `mcp-zenml.mcpb` file from the429root of this repository onto the menu and it will guide you through the430installation and setup process. You'll need to add your ZenML server URL and API key.431432Note: MCP bundles (`.mcpb`) replace the older Desktop Extensions (`.dxt`) format; existing `.dxt` files still work in Claude Desktop.433434#### Optional: Improving ZenML Tool Output Display435436For a better experience with ZenML tool results, you can configure Claude to437display the JSON responses in a more readable format. In Claude Desktop, go to438Settings → Profile, and in the "What personal preferences should Claude consider439in responses?" section, add something like the following (or use these exact440words!):441442```markdown443When 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!444```445446This will encourage Claude to format ZenML tool outputs as markdown tables,447making the information much easier to read and understand.448449### Installation for use with Cursor450451> **Quick alternative:** The MCP Settings page in your ZenML dashboard (Settings → MCP) can generate the exact `mcp.json` content with your credentials pre-filled.452453You will need to have [Cursor](https://www.cursor.com/) installed.454455Cursor works slightly differently to Claude Desktop in that you specify the456config file on a per-repository basis. This means that if you want to use the457ZenML MCP server in multiple repos, you will need to specify the config file in458each of them.459460To set it up for a single repository, you will need to:461462- create a `.cursor` folder in the root of your repository463- inside it, create a `mcp.json` file with the content above464- go into your Cursor settings and click on the ZenML server to 'enable' it.465466In our experience, sometimes it shows a red error indicator even though it is467working. You can try it out by chatting in the Cursor chat window. It will let468you know if is able to access the ZenML tools or not.469470## Docker Image471472You can run the server as a Docker container. The process communicates over stdio, so it will wait for an MCP client connection. Pass your ZenML credentials via environment variables.473474### Prebuilt Images (Docker Hub)475476Pull the latest multi-arch image:477478```bash479docker pull zenmldocker/mcp-zenml:latest480```481482Versioned releases are tagged as `X.Y.Z`:483484```bash485docker pull zenmldocker/mcp-zenml:1.0.8486```487488Run with your ZenML credentials (stdio mode):489490```bash491docker run -i --rm \492 -e ZENML_STORE_URL="https://your-zenml-server.example.com" \493 -e ZENML_STORE_API_KEY="your-api-key" \494 zenmldocker/mcp-zenml:latest495```496497### Canonical MCP config using Docker498499```json500{501 "mcpServers": {502 "zenml": {503 "command": "docker",504 "args": [505 "run", "-i", "--rm",506 "-e", "ZENML_STORE_URL=https://...",507 "-e", "ZENML_STORE_API_KEY=ZENKEY_...",508 "-e", "ZENML_ACTIVE_PROJECT_ID=...",509 "-e", "LOGLEVEL=WARNING",510 "-e", "NO_COLOR=1",511 "-e", "ZENML_LOGGING_COLORS_DISABLED=true",512 "-e", "ZENML_LOGGING_VERBOSITY=WARN",513 "-e", "ZENML_ENABLE_RICH_TRACEBACK=false",514 "-e", "PYTHONUNBUFFERED=1",515 "-e", "PYTHONIOENCODING=UTF-8",516 "zenmldocker/mcp-zenml:latest"517 ]518 }519 }520}521```522523### Build Locally524525From the repository root:526527```bash528docker build -t zenmldocker/mcp-zenml:local .529```530531Run the locally built image:532533```bash534docker run -i --rm \535 -e ZENML_STORE_URL="https://your-zenml-server.example.com" \536 -e ZENML_STORE_API_KEY="your-api-key" \537 zenmldocker/mcp-zenml:local538```539540## MCP Bundles (.mcpb)541542This project uses MCP Bundles (`.mcpb`) — the successor to Anthropic's Desktop Extensions (DXT). MCP Bundles package an entire MCP server (including dependencies) into a single file with user-friendly configuration.543544Note on rename: MCP Bundles replace the older `.dxt` format. Claude Desktop remains backward‑compatible with existing `.dxt` files, but we now ship `mcp-zenml.mcpb` and recommend using it going forward.545546The `mcp-zenml.mcpb` file in the repository root contains everything needed to run the ZenML MCP server, eliminating the need for complex manual installation steps. This makes powerful ZenML integrations accessible to users without requiring technical setup expertise.547548When you drag and drop the `.mcpb` file into Claude Desktop's settings, it automatically handles:549- Runtime dependency installation550- Secure configuration management551- Cross-platform compatibility552- User-friendly setup process553554For more information, see Anthropic's announcement of Desktop Extensions (DXT) and related MCP bundle packaging guidance in their documentation: https://www.anthropic.com/engineering/desktop-extensions555556## Published on the Anthropic MCP Registry557558This MCP server is published to the official Anthropic MCP Registry and is discoverable by compatible hosts. On each **tagged release**, our CI updates the registry entry via the registry’s `mcp-publisher` CLI using GitHub OIDC, so you can install or discover the **ZenML MCP Server** directly wherever the registry is supported (e.g., Claude Desktop’s Extensions catalog).559560- **Always up to date:** the registry entry is refreshed with every release from the tagged commit’s `manifest.json` and `server.json`.561- **Alternate install paths:** you can still install locally via the packaged `.mcpb` bundle (see above) or run the Docker image.562563Learn more about the registry here:564- Anthropic MCP Registry (community repo): https://github.com/modelcontextprotocol/registry565
Full transparency — inspect the skill content before installing.