ZenML

MCP-Server für ZenML

Dieses Projekt implementiert einen Model Context Protocol (MCP)-Server für die Interaktion mit der ZenML-API.

Was ist MCP?

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das standardisiert, wie Anwendungen Large Language Models (LLMs) Kontext bereitstellen. Es funktioniert wie ein „USB-C-Anschluss für KI-Anwendungen“ – und bietet eine standardisierte Möglichkeit, KI- Modelle mit verschiedenen Datenquellen und Tools zu verbinden.

MCP folgt einer Client-Server-Architektur mit:

• MCP-Hosts: Programme wie Claude Desktop oder IDEs, die über MCP auf Daten zugreifen möchten
• MCP-Clients: Protokollclients, die 1:1-Verbindungen zu Servern aufrechterhalten
• MCP-Server: Leichtgewichtige Programme, die über das standardisierte Protokoll bestimmte Funktionen bereitstellen
• Lokale Datenquellen: Dateien, Datenbanken und Dienste auf Ihrem Computer, auf die MCP-Server sicher zugreifen können
• Remote-Dienste: Externe Systeme, die über das Internet verfügbar sind und mit denen sich MCP-Server verbinden können

Was ist ZenML?

ZenML ist eine Open-Source-Plattform zum Erstellen und Verwalten von ML- und KI-Pipelines. Sie bietet eine einheitliche Schnittstelle zur Verwaltung von Daten, Modellen und Experimenten.

Weitere Informationen finden Sie auf der ZenML-Website und in unserer Dokumentation.

Funktionen

Der Server stellt MCP-Tools bereit, mit denen Sie auf zentrale Lesefunktionen des ZenML- Servers zugreifen und aktuelle Informationen zu folgenden Bereichen abrufen können:

Zentrale Entitäten

• Benutzer – Benutzerkonten und Berechtigungen
• Stacks – Infrastrukturkonfigurationen
• Stack-Komponenten – einzelne Bausteine eines Stacks
• Flavors – verfügbare Komponententypen
• Service-Connectors – Cloud-Authentifizierung

Pipeline-Ausführung

• Pipelines – Pipeline-Definitionen
• Pipeline-Runs – Ausführungsverlauf und Status
• Pipeline-Schritte – Details, Code und Logs einzelner Schritte
• Zeitpläne – Zeitpläne für automatisierte Runs
• Artefakte – Metadaten zu Datenartefakten (nicht die Daten selbst)

Deployment und Serving

• Snapshots – eingefrorene Pipeline-Konfigurationen (das Artefakt, das festlegt, „was ausgeführt/serviert werden soll“)
• Deployments – Serving-Instanzen zur Laufzeit mit Status, URL und Logs
• Dienste – Endpunkte für Model Serving

Organisation und Suche

• Projekte – organisatorische Container für ZenML-Ressourcen
• Tags – übergreifende Metadatenlabels zur Suche
• Builds – Pipeline-Build-Artefakte mit Informationen zu Images und Code

Modelle

• Modelle – Einträge in der ML-Modellregistrierung
• Modellversionen – versionierte Modellartefakte

Kompatibilitäts-APIs (Migration empfohlen)

• Pipeline-Run-Vorlagen sind in ZenML 0.97.0 weiterhin verfügbar, während für neue Workflows Snapshots bevorzugt werden (siehe Migrationsleitfaden)

Der Server ermöglicht außerdem, neue Pipeline-Runs auszulösen, indem Snapshots (bevorzugt) oder der veraltete vorlagenbasierte Trigger-Parameter verwendet werden.

Hinweis: Wir verbessern diese Integration kontinuierlich auf Grundlage des Feedbacks von Nutzern. Besuchen Sie unsere Slack-Community, um Ihre Erfahrungen zu teilen und uns dabei zu helfen, die Integration weiter zu verbessern!

Tool-Profile und Schreibzugriffsrichtlinie

Das standardmäßige Profil compact stellt 16 Tools bereit. Sieben generische Tools decken den Ressourcenkatalog, Lesezugriffe, gewöhnliche Änderungen und begrenzte Lebenszyklusaktionen ab:

Tool	Zweck
zenml_describe_resources	Unterstützte Ressourcentypen und begrenzte Operationsschemas ermitteln
zenml_list_resources	Einen Ressourcentyp mit validierten Filtern und Paginierung auflisten
zenml_get_resource	Eine Ressource abrufen, bei Bedarf mit übergeordnetem Element und Projektbereich
zenml_create_resource	Eine unterstützte Ressource aus einer typisierten Nutzlast erstellen
zenml_update_resource	Eine Ressource anhand ihrer exakten UUID aktualisieren
zenml_delete_resource	Eine Ressource anhand ihrer exakten UUID löschen oder archivieren
zenml_action_resource	Eine freigegebene Lebenszyklus- oder Beziehungsaktion ohne Wiederholungsversuche ausführen

Neun spezialisierte Tools bleiben erhalten, da sie Diagnosen, aktiven Kontext, gestreamte Logs oder Code, Pipeline-Ausführung oder eine interaktive App bereitstellen:

• diagnose_zenml_setup
• get_active_user und get_active_project
• trigger_pipeline
• get_step_logs, get_step_code und get_deployment_logs
• open_pipeline_run_dashboard und open_run_activity_chart

get_step_logs gibt höchstens 50,000 Einträge in chronologischer Reihenfolge zurück, mit einem possibly_truncated-Flag sowie einem note, das angibt, welche Einträge fehlen und warum. Übergeben Sie tail, um nur die neuesten Einträge abzurufen. Auf ZenML-Servern ab Version 0.97 wird der Log-Speicher seitenweise abgefragt; auf Version 0.96 wird der ältere Endpunkt für einzelne Anfragen verwendet.

Verwenden Sie ZENML_MCP_PROFILE=legacy, wenn ein vorhandener Client weiterhin von den alten entitätsspezifischen Namen wie list_pipeline_runs abhängt. Dadurch bleibt die kompatible Tool-Namens- und Schemaschicht für ZenML 0.97.0 erhalten. Die Unterstützung älterer ZenML-Serverversionen wird dadurch nicht hinzugefügt. Verwenden Sie dieses Profil nur während der Migration: Legacy-Antworten können mehr Betriebsmetadaten enthalten als die kompakten Tools, der Server lässt jedoch in beiden Profilen Konfigurationen mit Zugangsdaten und andere sensible Felder weg.

Registrierung und Schreibzugriff sind unabhängig voneinander:

Profil	Richtlinie	Bereitgestellte Tools
compact	read_write	16
compact	read_only	11
legacy	read_write	57
legacy	read_only	52

Setzen Sie ZENML_MCP_WRITE_POLICY=read_only, um alle vier generischen Änderungstools und trigger_pipeline aus der MCP-Erkennung und -Ausführung zu entfernen. Die Ressourcenerkennung lässt außerdem Schemas für Erstellen, Aktualisieren, Löschen und Aktionen weg. Die ältere Einstellung ZENML_MCP_READ_ONLY=true wird weiterhin akzeptiert; ungültige Richtlinienwerte führen aus Sicherheitsgründen zum Nur-Lese-Modus. Ein ungültiger Wert für ZENML_MCP_PROFILE führt beim Start zu einem Konfigurationsfehler.

Version 2.0.0 erfordert MCP Python SDK 2.2.0 und ZenML 0.96.4. Das kompakte Profil ist jetzt die Standardeinstellung und stellt eine inkompatible Änderung bei der Erkennung für Clients dar, die entitätsspezifische Tool-Namen aufrufen. Setzen Sie während der Migration dieser Clients ZENML_MCP_PROFILE=legacy und stellen Sie anschließend jeden Aufruf auf die generischen Ressourcentools um.

Änderungsergebnisse unterscheiden zwischen den Ergebnissen completed, accepted und unknown. Der Server wiederholt eine Änderung nicht, nachdem sie ZenML möglicherweise erreicht hat. Befolgen Sie bei einem akzeptierten oder unbekannten Ergebnis die Anweisungen zur Abstimmung in der Antwort, bevor Sie entscheiden, ob Sie den Aufruf wiederholen. Verwenden Sie, sofern verfügbar, den benannten Lesezugriff. Beim Erstellen von Webhooks und Rotieren von Secrets kann ein neues Signatur-Secret einmalig zurückgegeben werden; spätere Lesezugriffe lassen es weg. Löschschemas geben an, ob ein Vorgang Metadaten archiviert, Metadaten entfernt, eine aktive Ressource außer Betrieb nimmt oder gespeicherte Artefaktdaten löschen kann.

Die erste Version 2.0 deckt gewöhnliche Vorgänge für Projekte, Stacks und Komponenten, Flavors, Dienste, Pipelines und Runs, Snapshots und Vorlagen, Deployments, Artefakte und Versionen, Modelle und Versionen, Tags, Connectors, Code-Repositories, Webhooks, Trigger, Wartebedingungen und Hook-Aufrufe ab. Für Benutzer, Zeitpläne, Service-Connector-Typen, Secrets und Ressourcenanfragen gilt der in zenml_describe_resources gezeigte Nur-Lese-Zugriff. Nicht enthalten sind die Verwaltung der ZenML-Cloud-Control-Plane, die Verwaltung des Resource Managers, die Benutzer- und Zugangsdatenverwaltung, CRUD-Operationen für Secret-Werte, Connector-Anmeldung und -Verifizierung, unverarbeitete Webhook-Ereignisse sowie aggregierte Debugging- oder Lineage-Tools.

Beginnen Sie einen generischen Workflow, indem Sie das genaue Schema ermitteln und es anschließend aufrufen:

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 und Ressourcen sind in beiden Profilen weiterhin verfügbar. Die Analyse-Prompts, die begrenzten Ressourcenschema-Endpunkte und most_recent_runs sind MCP-Prompts oder -Ressourcen und keine Tools.

Kompatibilität von Run-Vorlagen

ZenML 0.97.0 behält CRUD-APIs für Run-Vorlagen bei. Für neue Workflows werden Snapshots bevorzugt. Die vereinfachte Pipeline-Erstellung und der vorlagenbasierte Trigger- Parameter sind veraltet. Im Legacy-Profil bleiben get_run_template und list_run_templates für bestehende Clients verfügbar.

Die Legacy-Eingabe tag bleibt aus Gründen der Schemakompatibilität in list_run_templates, aber ZenML 0.97.0 verfügt über keinen entsprechenden serverseitigen Filter. Ein Wert ungleich null wird vor dem SDK-Aufruf abgelehnt. Die Filterung von Snapshots nach Tags ist weiterhin verfügbar.

Migration: Run-Vorlagen → Snapshots

Warum die Änderung? Snapshots haben Run-Vorlagen als bevorzugtes ausführbares Pipeline-Artefakt in ZenML abgelöst. Das SDK 0.97.0 unterstützt weiterhin CRUD-Operationen für Run-Vorlagen, während neuer Code Snapshots verwenden sollte.

Kurzanleitung zur Migration

Legacy-Muster (Vorlagen)	Kompaktes Muster (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=...)

Beispielworkflow (Snapshots zuerst)

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)

Um Parameter beim Auslösen eines ausführbaren Snapshots zu überschreiben, übergeben Sie eine ZenML-Run- Konfiguration (der Snapshot selbst bleibt unverändert):

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

Bei statischen Snapshots überschreiben Sie Schrittparameter wie oben gezeigt. Überschreibungen auf oberster Ebene mit run_configuration={"parameters": {...}} betreffen Pipeline-Funktionsparameter und werden nur für dynamische Snapshots unterstützt; ZenML lehnt sie bei statischen Snapshots ab.

Hinweis: get_deployment_logs gibt eine begrenzte Ausgabe zurück (standardmäßig 100 Zeilen, maximal 1000, auf 100KB begrenzt) und erfordert die Installation der passenden Deployer-Integration.

Schnelleinrichtung über das Dashboard (empfohlen)

Am einfachsten richten Sie den ZenML-MCP-Server über die MCP-Einstellungsseite Ihres ZenML-Dashboards ein.

Navigieren Sie im ZenML-Dashboard zu Einstellungen → MCP, um Folgendes zu erhalten:

• Vorkonfigurierte Snippets für Ihre spezifische Server-URL und Zugangsdaten
• Installation mit einem Klick über Deep Links für unterstützte IDEs
• Konfigurationen zum Kopieren und Einfügen für VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex und mehr
• Docker- und uv-Optionen nach Ihren Wünschen

ZenML-Pro-Nutzer

Auf der MCP-Einstellungsseite können Sie mit einem Klick ein Personal Access Token (PAT) erstellen. Das Token wird automatisch in alle generierten Konfigurations-Snippets aufgenommen.

ZenML-OSS-Nutzer

1. Erstellen Sie zunächst über Einstellungen → Servicekonten ein Service-Account-Token
2. Fügen Sie das Token auf der MCP-Einstellungsseite ein
3. Kopieren Sie die generierte Konfiguration für Ihre IDE

---

Möchten Sie die Einrichtung lieber manuell vornehmen? Lesen Sie die ausführlichen Anweisungen weiter unten.

MCP-Apps (experimentell)

Was sind MCP-Apps? MCP-Apps sind interaktive HTML-Oberflächen, die MCP-Server direkt in KI-Clients bereitstellen können. Sie werden in Sandbox-Iframes gerendert und können bidirektional Server-Tools aufrufen. Ausführliche Informationen finden Sie in der offiziellen Ankündigung.

Dieser Server enthält zwei experimentelle MCP-Apps:

App	Tool	Beschreibung
Pipeline-Runs-Dashboard	open_pipeline_run_dashboard	Interaktive Tabelle der letzten Pipeline-Runs mit Status, Schrittdetails und Logs
Run-Aktivitätsdiagramm	open_run_activity_chart	Balkendiagramm der Pipeline-Run-Aktivität der letzten 30 Tage mit Aufschlüsselung nach Status

Diese Apps dienen als Proof-of-Concept-Beispiele. Wir freuen uns über Feedback und Beiträge zu weiteren MCP-Apps. Diese neue Funktion steckt noch in den Anfängen; wir müssen abwarten, wie sie sich entwickelt. Wir gehen davon aus, sie künftig umfassender zu unterstützen.

Unterstützte Clients

MCP-Apps erfordern den Streamable HTTP-Transport (nicht stdio). Die folgenden Clients unterstützen MCP-Apps derzeit:

• ✅ VS Code (Insiders Edition)
• ✅ Goose
• ✅ ChatGPT (Start in Kürze)
• ⚠️ Claude Desktop – rendert Apps laut Stand Ende Januar 2026 noch nicht.
• ⚠️ Claude.ai (Web) – rendert Apps laut Stand Ende Januar 2026 noch nicht.

Hinweis: Zum Zeitpunkt der Erstellung konnten wir Claude Desktop oder Claude.ai nicht gründlich testen. Sollten Probleme auftreten, melden Sie sie bitte.

MCP-Apps mit Docker ausführen

MCP-Apps verwenden Streamable HTTP. Binden Sie den Container-Port an die Loopback-Schnittstelle und schalten Sie einen authentifizierten Reverse-Proxy oder einen identitätsbasierten Zugriffsdienst davor, bevor Sie den Fernzugriff erlauben. Die Host- und Origin-Validierung schützt vor DNS-Rebinding; sie authentifiziert jedoch keine Aufrufer.

1. Docker-Container erstellen und ausführen:

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. Authentifizierten Fernzugriff konfigurieren:

Erstelle einen benannten Cloudflare Tunnel, einen Tailscale Funnel mit Zugriffskontrollen oder einen gleichwertigen authentifizierten Reverse-Proxy. Verweise mit dessen privatem Ursprung auf http://127.0.0.1:8001, verlange für den öffentlichen Hostnamen eine Identität oder Service-Anmeldedaten und leite nur authentifizierte Anfragen an den Ursprung weiter. Konfiguriere deinen MCP-Client so, dass er den unterstützten OAuth-Ablauf oder Autorisierungsheader des Anbieters verwendet.

Bevor du ZenML-Anmeldedaten zum Container hinzufügst, überprüfe, dass eine nicht authentifizierte Anfrage MCP nicht erreichen kann:

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

Die Antwort muss 401, 403 des Zugriffsanbieters oder eine Anmeldeumleitung sein. Eine JSON-RPC- oder MCP-Antwort bedeutet, dass die Zugriffsschranke offen ist und zuerst abgesichert werden muss.

3. Deinen authentifizierten Client verbinden:

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

• Bitte die KI, „das Dashboard für Pipeline-Ausführungen zu öffnen“ oder „das Aktivitätsdiagramm der Ausführungen anzuzeigen“

Wichtige Hinweise:

• ZENML_ACTIVE_PROJECT_ID ist erforderlich – ohne diesen Wert schlagen Pipeline-Ausführungstools mit „No project is currently set as active“ fehl
• --disable-dns-rebinding-protection ist nur dann geeignet, wenn der authentifizierte Proxy den öffentlichen Host überprüft und der Container-Port weiterhin nur über Loopback erreichbar ist
• Beschränke den ZenML-API-Schlüssel auf die Berechtigungen, die der MCP-Client benötigt; verwende ZENML_MCP_WRITE_POLICY=read_only für Clients, die nur Daten einsehen

Tests und Qualitätssicherung

Dieses Projekt umfasst automatisierte Tests, um sicherzustellen, dass der MCP-Server funktionsfähig bleibt:

• 🔄 Automatisierte Smoke-Tests: Alle 3 Tage wird über GitHub Actions ein umfassender Smoke-Test ausgeführt
• 🚨 Erstellung von Issues: Bei fehlgeschlagenen Tests werden automatisch GitHub-Issues mit detaillierten Informationen zur Fehlersuche erstellt
• ⚡ Schnelle CI: Verwendet UV mit Caching für eine schnelle Installation von Abhängigkeiten und Tests
• 🧪 Manuelle Tests: Du kannst den Smoke-Test lokal mit uv run scripts/test_mcp_server.py server/zenml_server.py ausführen

Die automatisierten Tests überprüfen:

• MCP-Protokollverbindung und Handshake
• Serverinitialisierung und Tool-Erkennung
• Grundlegende Tool-Funktionalität (wenn der ZenML-Server erreichbar ist)
• Aufzählung von Ressourcen und Prompts
• diagnose_zenml_setup gibt auch in eingeschränkten Umgebungen strukturierte Diagnosen zurück

Die CI ohne Anmeldedaten deckt jeden Adapter über das MCP-Protokoll ab. PR- und Release-CI starten außerdem einen frischen ZenML-0.97.0-OSS-Server unter einer Loopback-Adresse und führen persistierte CRUD- sowie Isolationsprüfungen für Projekte mit gleichem Namen aus. Der Server verwendet eine temporäre Konfiguration und Datenbank, die beim Beenden des Jobs entfernt werden; eine Repository-Umgebung, ein selbst gehosteter Runner oder ZenML-Anmeldedaten sind nicht erforderlich.

Der lokale OSS-Server von ZenML deaktiviert die Authentifizierung, und sein SQL-Speicher unterstützt weder die Wiedergabe von Pipelines noch externe Bereitstellungsinfrastruktur. Prüfungen für eingeschränkten Zugriff sowie für Trigger, Wiedergabe, Bereitstellung, Wartebedingungen und Ressourcenanforderungen mit aktivierten Funktionen bleiben daher separate optionale Gates. Sie erfordern ZENML_MCP_RESTRICTED_INTEGRATION=1 mit ZENML_MCP_RESTRICTED_API_KEY beziehungsweise ZENML_MCP_ACTION_INTEGRATION=1 mit den exakten UUIDs der temporären Fixtures in ZENML_MCP_ACTION_FIXTURE. Ein übersprungener Gate-Test ist kein Nachweis dafür, dass diese Funktionen erfolgreich getestet wurden. Ein Operator kann ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 setzen, damit ein fehlendes optionales Gate als Fehler gewertet wird. Die Bereitstellung von Cloud-Infrastruktur ist niemals Teil des standardmäßigen Testlaufs.

Fehlersuche mit MCP Inspector

Verwende zur interaktiven Fehlersuche den MCP Inspector – ein webbasiertes Tool, mit dem du MCP-Tools in Echtzeit testen kannst:

# 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

Dadurch wird eine Weboberfläche mit vorausgefüllten Anmeldedaten geöffnet – klicke einfach auf Connect und verwende den Tab Tools, um beliebige Tools interaktiv zu testen.

Ausführlichere Anweisungen zur Fehlersuche findest du unter CLAUDE.md.

Datenschutz und Analysen

Der ZenML MCP Server erfasst anonyme Nutzungsanalysen, damit wir das Produkt verbessern können.

Wir erfassen:

• Welche Tools wie oft verwendet werden
• Fehlerraten und Fehlertypen (nur den Fehlertyp, keine Meldungen)
• Grundlegende Umgebungsinformationen (Betriebssystem, Python-Version und ob die Ausführung in Docker/CI erfolgt)
• Sitzungsdauer und Nutzungsmuster der Tools

Wir erfassen NICHT:

• Die URL deines ZenML-Servers oder deinen API-Schlüssel
• Pipeline-Namen, Modellnamen oder Geschäftsdaten
• Fehlermeldungen oder Stacktraces
• Personenbezogene Daten

So deaktivierst du Analysen:

# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false

# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true

Für Fehlersuche und Tests (Ereignisse werden in stderr protokolliert, statt gesendet):

export ZENML_MCP_ANALYTICS_DEV=true

Für Docker-Nutzer: Du kannst ZENML_MCP_ANALYTICS_ID (muss eine gültige UUID sein) setzen, um über Container-Neustarts hinweg eine einheitliche anonyme ID beizubehalten. Wenn du den Wert nicht setzt und das Container-Dateisystem die Datei mit der Analytics-ID nicht speichern kann, verwendet der Server stattdessen eine deterministische anonyme UUID, die aus einem Hash von ZENML_STORE_URL abgeleitet wird (die URL selbst wird niemals als Ereigniseigenschaft gesendet).

Zusätzliche Analyseoptionen:

• ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S – maximale Zeit (Sekunden), um Analysen beim Herunterfahren synchron zu übertragen (Standard: 1.0)

Hinweis zur Erfassung beim Herunterfahren: Ereignisse zum Herunterfahren werden synchron mit einer begrenzten Zeitüberschreitung gesendet, um die zuverlässige Übermittlung zu verbessern. Wird ein Container jedoch mit SIGKILL beendet (z. B. mit docker kill), können Handler für das Herunterfahren nicht ausgeführt werden – das ist eine Einschränkung von Docker bzw. des Betriebssystems und kein Fehler.

Startvalidierung

Du kannst eine einfache Diagnoseprüfung beim Start aktivieren:

# 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

Du kannst dies auch über die Umgebungsvariable ZENML_MCP_STARTUP_VALIDATION=warn festlegen.

Das Tool diagnose_zenml_setup ist außerdem als MCP-Tool zur Laufzeit-Fehlersuche verfügbar – es funktioniert auch dann, wenn das ZenML SDK nicht installiert ist oder Umgebungsvariablen fehlen.

Manuelle Einrichtung

Voraussetzungen

Du benötigst Zugriff auf einen bereitgestellten ZenML-Server. Falls du noch keinen hast, kannst du dich für eine kostenlose Testversion bei ZenML Pro anmelden; wir übernehmen dann die Bereitstellung für dich.

Tipp: Sobald du einen ZenML-Server hast, findest du in deinem Dashboard auf der Seite MCP Settings die einfachste Möglichkeit zur Einrichtung.

Kompatibilität: Die aktuelle Version wurde mit ZenML 0.97.0 getestet. Wenn du eine ältere ZenML-Version verwendest, nutze bitte eine frühere Version dieses MCP-Servers.

Außerdem musst du wahrscheinlich uv lokal installiert haben. Weitere Informationen findest du in der Dokumentation zu uv. Wir empfehlen die Installation über das Installationsskript oder über brew, wenn du einen Mac verwendest. (Technisch gesehen ist es nicht zwingend erforderlich, aber es vereinfacht Installation und Einrichtung.)

Außerdem musst du dieses Repository an einem lokalen Speicherort klonen:

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

Deine MCP-Konfigurationsdatei

Die MCP-Konfigurationsdatei ist eine JSON-Datei, die dem MCP-Client mitteilt, wie er sich mit deinem MCP-Server verbinden soll. Verschiedene MCP-Clients verwenden oder definieren diese Datei unterschiedlich. Zwei häufig verwendete MCP-Clients sind Claude Desktop und Cursor, für die wir unten Installationsanweisungen bereitstellen.

Du musst deinen ZenML MCP-Server im folgenden Format angeben:

{
    "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"
            }
        }
    }
}

Wenn ZENML_STORE_API_KEY angegeben ist, speichert der MCP-Server deine ZenML-Anmeldedaten im Arbeitsspeicher und liest die von zenml login gespeicherten Anmeldedaten weder aus noch aktualisiert er sie. Dies gilt für direkte Python-Ausführungen, MCPB-Erweiterungen und Docker. Verbindungen ohne API-Schlüssel können weiterhin deine gespeicherte Terminalanmeldung verwenden. Starte den MCP-Server neu, nachdem du seinen API-Schlüssel geändert hast; ein neuer Chat allein verwendet möglicherweise weiterhin den laufenden Serverprozess.

Es gibt vier Platzhalterwerte, die du ersetzen musst:

• den Pfad zu deiner lokal installierten uv (der oben aufgeführte Pfad entspricht dem Speicherort auf einem Mac, wenn du die Installation über brew vorgenommen hast)
• den Pfad zur Datei zenml_server.py (diese Datei wird ausgeführt, wenn du dich mit dem MCP-Server verbindest). Sie befindet sich im Stammverzeichnis dieses Repositorys. Du musst den vollständigen, exakten Pfad zu dieser Datei angeben.
• die URL des ZenML-Servers (dies ist die URL deines ZenML-Servers. Du findest sie in der ZenML Cloud UI). Sie sieht etwa so aus: https://d534d987a-zenml.cloudinfra.zenml.io.
• den API-Schlüssel des ZenML-Servers (dies ist der API-Schlüssel für deinen ZenML-Server. Du findest ihn in der ZenML Cloud UI oder kannst diese Dokumentation lesen, um zu erfahren, wie du einen erstellst. Für den ZenML MCP Server empfehlen wir die Verwendung eines Servicekontos.)

Du kannst die Python-Datei des MCP-Servers auf beliebige Weise ausführen. uv ist jedoch wahrscheinlich die einfachste Option, da damit die Umgebung und die Installation der Abhängigkeiten für dich verwaltet werden.

Installation für Claude Desktop

Schnelle Alternative: Auf der MCP Settings-Seite in deinem ZenML-Dashboard (Settings → MCP) findest du vorkonfigurierte Installationsanweisungen und Deeplinks für Claude Desktop.

Du musst die neueste Version von Claude Desktop installiert haben.

Du kannst einfach das Menü „Settings“ öffnen und die Datei mcp-zenml.mcpb aus dem Stammverzeichnis dieses Repositorys auf das Menü ziehen. Anschließend wirst du durch die Installation und Einrichtung geführt. Du musst die URL und den API-Schlüssel deines ZenML-Servers hinzufügen.

Hinweis: MCP-Bundles (.mcpb) ersetzen das ältere Format Desktop Extensions (.dxt); vorhandene Dateien vom Typ .dxt funktionieren weiterhin in Claude Desktop.

Optional: Anzeige der ZenML-Toolausgabe verbessern

Für eine bessere Darstellung der Ergebnisse von ZenML-Tools kannst du Claude so konfigurieren, dass JSON-Antworten lesbarer angezeigt werden. Gehe in Claude Desktop zu Settings → Profile und füge im Abschnitt „What personal preferences should Claude consider in responses?“ beispielsweise Folgendes hinzu (oder verwende genau diesen Wortlaut!):

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!

Dadurch wird Claude dazu angehalten, Ausgaben von ZenML-Tools als Markdown-Tabellen zu formatieren, sodass die Informationen deutlich leichter zu lesen und zu verstehen sind.

Installation für Cursor

Schnelle Alternative: Auf der MCP Settings-Seite in deinem ZenML-Dashboard (Settings → MCP) kannst du den exakten Inhalt von mcp.json mit vorausgefüllten Anmeldedaten generieren.

Du musst Cursor installiert haben.

Cursor funktioniert etwas anders als Claude Desktop: Die Konfigurationsdatei wird für jedes Repository einzeln angegeben. Wenn du den ZenML MCP Server in mehreren Repositories verwenden möchtest, musst du die Konfigurationsdatei daher in jedem einzelnen angeben.

Für die Einrichtung in einem einzelnen Repository musst du:

• im Stammverzeichnis deines Repositorys einen Ordner .cursor erstellen
• darin eine Datei mcp.json mit dem obigen Inhalt erstellen
• in den Cursor-Einstellungen auf den ZenML-Server klicken, um ihn zu „aktivieren“.

Unserer Erfahrung nach wird manchmal eine rote Fehlermarkierung angezeigt, obwohl der Server funktioniert. Du kannst es ausprobieren, indem du im Cursor-Chatfenster schreibst. Cursor teilt dir mit, ob es auf die ZenML-Tools zugreifen kann.

Docker-Image

Du kannst den Server als Docker-Container ausführen. Der Prozess kommuniziert über stdio und wartet daher auf eine Verbindung von einem MCP-Client. Übergib deine ZenML-Anmeldedaten über Umgebungsvariablen.

Vorgefertigte Images (Docker Hub)

Lade das neueste Multi-Arch-Image herunter:

docker pull zenmldocker/mcp-zenml:latest

Versionierte Releases sind mit X.Y.Z gekennzeichnet:

docker pull zenmldocker/mcp-zenml:2.0.0

Führe den Container mit deinen ZenML-Anmeldedaten aus (stdio-Modus):

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

Kanonische MCP-Konfiguration mit 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"
      ]
    }
  }
}

Lokal erstellen

Führe im Stammverzeichnis des Repositorys Folgendes aus:

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

Führe das lokal erstellte Image aus:

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)

Dieses Projekt verwendet MCP-Bundles (.mcpb) – den Nachfolger von Anthropics Desktop Extensions (DXT). MCP-Bundles verpacken einen vollständigen MCP-Server (einschließlich Abhängigkeiten) in einer einzelnen Datei mit benutzerfreundlicher Konfiguration.

Hinweis zur Umbenennung: MCP-Bundles ersetzen das ältere Format .dxt. Claude Desktop ist weiterhin abwärtskompatibel mit vorhandenen Dateien vom Typ .dxt, aber wir liefern jetzt mcp-zenml.mcpb aus und empfehlen, dieses Format künftig zu verwenden.

Die Datei mcp-zenml.mcpb im Stammverzeichnis des Repositorys verwendet die MCPB-0.4-UV-Laufzeitumgebung. Der Host installiert die festgelegten Python-Abhängigkeiten für das aktuelle Betriebssystem, sodass dasselbe Bundle unter macOS, Windows und Linux funktioniert, ohne plattformabhängige native Erweiterungen einzubetten. Beim ersten Auflösen der gebündelten Umgebung durch UV ist eine Netzwerkverbindung erforderlich. Bundle-Builds verwenden das committete mcpb-uv.lock wieder und lösen dessen Python-Abhängigkeitsgraphen im Offline-Modus auf. Die Abhängigkeitsliste des Bundles stammt aus [project].dependencies in pyproject.toml. Nachdem du diese Liste geändert hast, setze MCPB_REFRESH_LOCK=1, um die Abhängigkeiten online neu aufzulösen und dabei alle Pins beizubehalten, die weiterhin passen; MCPB_REFRESH_LOCK=upgrade aktualisiert alle Pins auf ihre jeweils neueste Version.

Wenn du die Datei .mcpb per Drag-and-drop in die Einstellungen von Claude Desktop ziehst, werden automatisch folgende Schritte ausgeführt:

• Installation der Laufzeitabhängigkeiten
• Sichere Konfigurationsverwaltung
• Plattformübergreifende Kompatibilität
• Benutzerfreundlicher Einrichtungsprozess

Weitere Informationen findest du in Anthropics Ankündigung zu Desktop Extensions (DXT) und den zugehörigen Hinweisen zur MCP-Bundle-Paketierung in der Dokumentation: https://www.anthropic.com/engineering/desktop-extensions

Im Anthropic MCP Registry veröffentlicht

Dieser MCP-Server ist im offiziellen Anthropic MCP Registry veröffentlicht und für kompatible Hosts auffindbar. Bei jedem getaggten Release aktualisiert unsere CI den Registry-Eintrag über die mcp-publisher-CLI mithilfe von GitHub OIDC. So kannst du den ZenML MCP Server direkt überall dort installieren oder finden, wo das Registry unterstützt wird (z. B. im Extensions-Katalog von Claude Desktop).

• Immer auf dem neuesten Stand: Der Registry-Eintrag wird bei jedem Release anhand des manifest.json und server.json des getaggten Commits aktualisiert.
• Alternative Installationswege: Du kannst weiterhin lokal über das gepackte .mcpb-Bundle installieren (siehe oben) oder das Docker-Image ausführen.

Weitere Informationen zum Registry findest du hier:

• Anthropic MCP Registry (Community-Repository): https://github.com/modelcontextprotocol/registry