ZenML

ZenML için MCP Sunucusu

Bu proje, ZenML API’siyle etkileşim kurmak için bir Model Context Protocol (MCP) sunucusu uygular.

MCP nedir?

Model Context Protocol (MCP), uygulamaların Büyük Dil Modellerine (LLM’ler) nasıl bağlam sağladığını standartlaştıran açık bir protokoldür. “Yapay zekâ uygulamaları için USB-C bağlantı noktası” gibi çalışır; yapay zekâ modellerini farklı veri kaynaklarına ve araçlara bağlamak için standart bir yol sunar.

MCP, istemci-sunucu mimarisini izler:

• MCP Ana Bilgisayarları: MCP aracılığıyla verilere erişmek isteyen Claude Desktop veya IDE’ler gibi programlar
• MCP İstemcileri: Sunucularla 1:1 bağlantıları sürdüren protokol istemcileri
• MCP Sunucuları: Standartlaştırılmış protokol aracılığıyla belirli yetenekleri sunan hafif programlar
• Yerel Veri Kaynakları: MCP sunucularının güvenli bir şekilde erişebildiği bilgisayarınızdaki dosyalar, veritabanları ve hizmetler
• Uzak Hizmetler: MCP sunucularının bağlanabildiği, internet üzerinden kullanılabilen harici sistemler

ZenML nedir?

ZenML, ML ve yapay zekâ işlem hatları oluşturmak ve yönetmek için açık kaynaklı bir platformdur. Verileri, modelleri ve deneyleri yönetmek için birleşik bir arayüz sunar.

Daha fazla bilgi için ZenML web sitesine ve belgelerimize bakın.

Özellikler

Sunucu, ZenML sunucusunun temel okuma işlevlerine erişmek için MCP araçları sağlar ve aşağıdakiler hakkında güncel bilgi edinmenize olanak tanır:

Temel Varlıklar

• Kullanıcılar - kullanıcı hesapları ve izinler
• Yığınlar - altyapı yapılandırmaları
• Yığın Bileşenleri - yığınları oluşturan bağımsız yapı taşları
• Tatlar - kullanılabilir bileşen türleri
• Hizmet Bağlayıcıları - bulut kimlik doğrulaması

İş Hattı Yürütme

• İş Hatları - iş hattı tanımları
• İş Hattı Çalıştırmaları - yürütme geçmişi ve durumu
• İş Hattı Adımları - adımlara ait ayrıntılar, kod ve günlükler
• Zamanlamalar - otomatik çalıştırma zamanlamaları
• Yapıtlar - veri yapıtlarına ilişkin meta veriler (verilerin kendisi değil)

Dağıtım ve Sunum

• Anlık Görüntüler - dondurulmuş iş hattı yapılandırmaları (“çalıştırılacak/sunulacak olan” yapıt)
• Dağıtımlar - durumu, URL’si ve günlükleri olan çalışma zamanı sunum örnekleri
• Hizmetler - model sunum uç noktaları

Organizasyon ve Keşif

• Projeler - ZenML kaynakları için organizasyon kapsayıcıları
• Etiketler - keşif için farklı alanlarda kullanılan meta veri etiketleri
• Derlemeler - görüntü ve kod bilgilerini içeren iş hattı derleme yapıtları

Modeller

• Modeller - ML model kayıt defteri girdileri
• Model Sürümleri - sürümlenmiş model yapıtları

Uyumluluk API’leri (geçiş önerilir)

• İş hattı çalıştırma şablonları ZenML 0.97.0’da kullanılabilir olmaya devam ederken, yeni iş akışları için Anlık Görüntüler tercih edilir (Geçiş Kılavuzu’na bakın)

Sunucu ayrıca anlık görüntüleri (tercih edilen yöntem) veya kullanımdan kaldırılmış şablon tabanlı tetikleme parametresini kullanarak yeni iş hattı çalıştırmaları başlatmanıza olanak tanır.

Not: Bu entegrasyonu kullanıcı geri bildirimlerine göre sürekli geliştiriyoruz. Deneyiminizi paylaşmak ve entegrasyonu daha da iyileştirmemize yardımcı olmak için lütfen Slack topluluğumuza katılın!

Araç profilleri ve yazma ilkesi

Varsayılan compact profili 16 araç sunar. Yedi genel araç; kaynak kataloğunu, okuma işlemlerini, olağan değişiklikleri ve sonlu yaşam döngüsü eylemlerini kapsar:

Araç	Amaç
zenml_describe_resources	Desteklenen kaynak türlerini ve sınırlandırılmış işlem şemalarını keşfetme
zenml_list_resources	Doğrulanmış filtreler ve sayfalama ile tek bir kaynak türünü listeleme
zenml_get_resource	Gerektiğinde üst öğe ve proje kapsamıyla tek bir kaynağı alma
zenml_create_resource	Türü belirlenmiş bir yükten desteklenen bir kaynak oluşturma
zenml_update_resource	Tam UUID’si belirtilen tek bir kaynağı güncelleme
zenml_delete_resource	Tam UUID’si belirtilen tek bir kaynağı silme veya arşivleme
zenml_action_resource	Yeniden deneme yapmadan izin verilen bir yaşam döngüsü veya ilişki eylemini yürütme

Dokuz özel araç; tanılama, etkin bağlam, akış hâlindeki günlükler veya kod, iş hattı yürütme ya da etkileşimli bir App sağladıkları için kullanılmaya devam eder:

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

get_step_logs, en fazla 50,000 girdiyi en eskiden başlayarak ve bir possibly_truncated bayrağıyla birlikte döndürür; ayrıca hangi girdilerin eksik olduğunu ve nedenini belirten bir note sunar. Yalnızca en yeni girdileri almak için tail değerini iletin. ZenML 0.97+ sunucularında günlük deposunda sayfalama yapar; 0.96’da ise eski tek istekli uç noktayı kullanır.

Mevcut bir istemci hâlâ list_pipeline_runs gibi eski varlığa özgü adlara bağlıysa ZENML_MCP_PROFILE=legacy kullanın. Bu, ZenML 0.97.0 için karakterize edilmiş araç adı ve şema uyumluluk katmanını korur. Daha eski ZenML sunucu sürümlerini desteklemez. Yalnızca geçiş sırasında kullanın: eski yanıt biçimleri, kompakt araçlara kıyasla daha fazla operasyonel meta veri sunabilir; ancak sunucu, her iki profilde de kimlik bilgisi içeren yapılandırmaları ve diğer hassas alanları çıkarır.

Kayıt ve yazma erişimi birbirinden bağımsızdır:

Profil	İlke	Sunulan araçlar
compact	read_write	16
compact	read_only	11
legacy	read_write	57
legacy	read_only	52

Dört genel değişiklik aracının tümünü ve trigger_pipeline öğesini MCP keşfinden ve dağıtımından kaldırmak için ZENML_MCP_WRITE_POLICY=read_only değerini ayarlayın. Kaynak keşfi de oluşturma, güncelleme, silme ve eylem şemalarını çıkarır. Eski ZENML_MCP_READ_ONLY=true ayarı kabul edilmeye devam eder; geçersiz ilke değerleri güvenli biçimde salt okunur moda geçer. Geçersiz bir ZENML_MCP_PROFILE başlangıcı yapılandırma hatasıyla durdurur.

2.0.0 sürümü MCP Python SDK 2.2.0 ve ZenML 0.96.4 gerektirir. Yeni varsayılan olan kompakt profil, varlığa özgü araç adlarını çağıran istemciler için keşif davranışında geriye dönük uyumsuz bir değişikliktir. Bu istemcileri geçirirken ZENML_MCP_PROFILE=legacy değerini ayarlayın, ardından her çağrıyı genel kaynak araçlarına taşıyın.

Değişiklik sonuçları completed, accepted ve unknown sonuçlarını birbirinden ayırır. ZenML’e ulaşmış olabilecek bir değişiklik isteği sunucu tarafından yeniden denenmez. Sonuç kabul edilmiş veya bilinmiyorsa, yeniden çağrı yapıp yapmayacağınıza karar vermeden önce yanıttaki uzlaştırma talimatlarını izleyin. Kullanılabilir olduğunda adı belirtilen okuma aracını kullanın. Webhook oluşturma ve gizli anahtar döndürme işlemleri yeni bir imzalama gizli anahtarını bir kez döndürebilir; sonraki okumalar bu anahtarı içermez. Silme şemaları, bir işlemin meta verileri arşivleyip arşivlemediğini, kaldırıp kaldırmadığını, canlı bir kaynağı devre dışı bırakıp bırakmadığını veya depolanmış yapıt verilerini silebilip silemediğini belirtir.

İlk 2.0 sürümü; projeler, yığınlar ve bileşenler, tatlar, hizmetler, iş hatları ve çalıştırmalar, anlık görüntüler ve şablonlar, dağıtımlar, yapıtlar ve sürümler, modeller ve sürümler, etiketler, bağlayıcılar, kod depoları, webhook’lar, tetikleyiciler, bekleme koşulları ve hook çağrıları için olağan işlemleri kapsar. Kullanıcılar, zamanlamalar, hizmet bağlayıcı türleri, gizli bilgiler ve kaynak istekleri, zenml_describe_resources ile gösterilen salt okunur kapsama sahiptir. ZenML Cloud kontrol düzlemi yönetimini, Resource Manager yönetimini, kullanıcı ve kimlik bilgisi yönetimini, gizli değerler üzerinde CRUD işlemlerini, bağlayıcı oturum açma ve doğrulama işlemlerini, ham webhook olaylarını ve toplu hata ayıklama veya soy ağacı araçlarını kapsamaz.

Genel bir iş akışına, kesin şemayı keşfederek başlayın ve ardından aracı çağırı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,
)

İstemler ve kaynaklar her iki profilde de kullanılabilir. Analiz istemleri, sınırlandırılmış kaynak şeması uç noktaları ve most_recent_runs, araç değil MCP istemleri veya kaynaklarıdır.

Çalıştırma şablonu uyumluluğu

ZenML 0.97.0, çalıştırma şablonu CRUD API’lerini korur. Yeni iş akışları için anlık görüntüler tercih edilir. İş hattı kolaylık amaçlı oluşturma ve şablon tabanlı tetikleme parametresi kullanımdan kaldırılmıştır. Eski profilde get_run_template ve list_run_templates, mevcut istemciler için kullanılabilir olmaya devam eder.

Eski tag girdisi, şema uyumluluğu için list_run_templates içinde kalır; ancak ZenML 0.97.0’da bunun sunucu tarafında karşılığı olan bir filtre yoktur. Null olmayan bir değer, SDK çağrısından önce reddedilir. Anlık görüntü etiketlerine göre filtreleme kullanılabilir olmaya devam eder.

Geçiş: Çalıştırma Şablonları → Anlık Görüntüler

Bu değişiklik neden yapıldı? Anlık görüntüler, ZenML’in çalıştırılabilir iş hattı yapıtı olarak tercih ettiği seçenek hâline gelerek çalıştırma şablonlarının yerini aldı. 0.97.0 SDK’sı çalıştırma şablonu CRUD işlemlerini hâlâ destekler; yeni kod ise anlık görüntüleri kullanmalıdır.

Hızlı Geçiş Kılavuzu

Eski Kalıp (Şablonlar)	Kompakt Kalıp (Anlık Görüntüler)
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=...)

Örnek İş Akışı (Önce Anlık Görüntü)

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)

Çalıştırılabilir bir anlık görüntüyü tetiklerken parametreleri geçersiz kılmak için ZenML çalıştırma yapılandırması iletin (anlık görüntünün kendisi değişmeden kalır):

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

Statik anlık görüntüler için adım parametrelerini yukarıda gösterildiği gibi geçersiz kılın. Üst düzey run_configuration={"parameters": {...}}, iş hattı işlevi parametrelerini geçersiz kılar ve yalnızca dinamik anlık görüntülerde desteklenir; ZenML bunu statik anlık görüntüler için reddeder.

Not: get_deployment_logs, sınırlandırılmış çıktı döndürür (varsayılan 100 satır, en fazla 1000 satır, 100KB ile sınırlı) ve uygun dağıtıcı entegrasyonunun yüklenmiş olmasını gerektirir.

Pano Üzerinden Hızlı Kurulum (Önerilen)

ZenML MCP Sunucusunu kurmanın en kolay yolu, ZenML panonuzdaki MCP Settings sayfasını kullanmaktır.

Aşağıdakilere erişmek için ZenML panonuzda Settings → MCP bölümüne gidin:

• Sunucunuza özel URL ve kimlik bilgileriyle önceden yapılandırılmış kod parçacıkları
• Desteklenen IDE’ler için derin bağlantılar aracılığıyla tek tıklamayla kurulum
• VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex ve daha fazlası için kopyala-yapıştır yapılandırmaları
• Tercihinize göre Docker ve uv seçenekleri

ZenML Pro Kullanıcıları

MCP Settings sayfası, tek tıklamayla Kişisel Erişim Belirteci (PAT) oluşturmanıza olanak tanır. Belirteç, oluşturulan tüm yapılandırma kod parçacıklarına otomatik olarak eklenir.

ZenML OSS Kullanıcıları

1. Önce Settings → Service Accounts üzerinden bir hizmet hesabı belirteci oluşturun
2. Belirteci MCP Settings sayfasına yapıştırın
3. IDE’niz için oluşturulan yapılandırmayı kopyalayın

---

Elle kurulum mu tercih ediyorsunuz? Ayrıntılı talimatlar için aşağıya bakın.

MCP Apps (Deneysel)

MCP Apps nedir? MCP Apps, MCP sunucularının doğrudan yapay zekâ istemcilerine sunabildiği etkileşimli HTML arayüzleridir. Yalıtılmış iframe’lerde görüntülenir ve sunucu araçlarını çift yönlü olarak çağırabilirler. Ayrıntılar için resmî duyuruya bakın.

Bu sunucu iki deneysel MCP App içerir:

App	Araç	Açıklama
İş Hattı Çalıştırmaları Panosu	open_pipeline_run_dashboard	Durum, adım ayrıntıları ve günlüklerle birlikte son iş hattı çalıştırmalarını gösteren etkileşimli tablo
Çalıştırma Etkinliği Grafiği	open_run_activity_chart	Durum dökümüyle birlikte son 30 gündeki iş hattı çalıştırma etkinliğini gösteren çubuk grafik

Bu uygulamalar kavram kanıtı örnekleri olarak eklenmiştir. Geri bildirimlerinizi ve daha fazla MCP App katkılarınızı bekliyoruz. Bu yeni özellik henüz çok erken aşamada; nasıl gelişeceğini göreceğiz. Gelecekte daha kapsamlı destek sunmayı bekliyoruz.

Desteklenen İstemciler

MCP Apps, Streamable HTTP aktarımını gerektirir (stdio değil). Aşağıdaki istemciler şu anda MCP Apps’i desteklemektedir:

• ✅ VS Code (Insiders Edition)
• ✅ Goose
• ✅ ChatGPT (yakında kullanıma sunuluyor)
• ⚠️ Claude Desktop -- Ocak 2026 sonu itibarıyla Apps’i henüz görüntüleyemiyor.
• ⚠️ Claude.ai (web) — Ocak 2026 sonu itibarıyla Apps’i henüz görüntüleyemiyor.

Not: Yazım sırasında Claude Desktop veya Claude.ai ile kapsamlı test yapamadık. Sorunlarla karşılaşırsanız lütfen bildirin.

MCP Apps’i Docker ile Çalıştırma

MCP Apps, Streamable HTTP kullanır. Uzak erişime izin vermeden önce kapsayıcı bağlantı noktasını loopback’e bağlayın ve önüne kimlik doğrulamalı bir ters proxy veya kimlik farkındalıklı erişim hizmeti koyun. Host ve Origin doğrulaması DNS yeniden bağlama saldırılarına karşı koruma sağlar; çağıranların kimliğini doğrulamaz.

1. Docker kapsayıcısını derleyin ve çalıştırın:

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. Kimliği doğrulanmış uzak erişimi yapılandırın:

Adlandırılmış bir Cloudflare Tunnel, erişim denetimleri olan bir Tailscale Funnel veya eşdeğer bir kimliği doğrulanmış ters proxy oluşturun. Özel kaynağını http://127.0.0.1:8001 adresine yönlendirin, genel ana makine adı için bir kimlik veya hizmet kimlik bilgisi isteyin ve kaynağa yalnızca kimliği doğrulanmış istekleri iletin. MCP istemcinizi, sağlayıcının desteklediği OAuth akışını veya yetkilendirme üst bilgilerini kullanacak şekilde yapılandırın.

ZenML kimlik bilgilerini kapsayıcıya eklemeden önce, kimliği doğrulanmamış bir isteğin MCP'ye ulaşamadığını doğrulayın:

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

Yanıt, erişim sağlayıcısının 401, 403 veya oturum açma yönlendirmesi olmalıdır. JSON-RPC ya da MCP yanıtı, çevre sınırının açık olduğu anlamına gelir ve önce bu sorun giderilmelidir.

3. Kimliği doğrulanmış istemcinizi bağlayın:

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

• Yapay zekâdan "iş hattı çalıştırmaları panosunu açmasını" veya "çalıştırma etkinliği grafiğini göstermesini" isteyin

Önemli notlar:

• ZENML_ACTIVE_PROJECT_ID gereklidir — bu olmadan iş hattı çalıştırma araçları "No project is currently set as active" hatası verir
• --disable-dns-rebinding-protection yalnızca kimliği doğrulanmış proxy genel ana makineyi doğruladığında ve kapsayıcı bağlantı noktası yalnızca loopback erişimine açık kaldığında uygundur
• ZenML API anahtarının izinlerini MCP istemcisinin ihtiyaç duyduğu izinlerle sınırlayın; yalnızca inceleme yapan istemciler için ZENML_MCP_WRITE_POLICY=read_only kullanın

Test ve Kalite Güvencesi

Bu proje, MCP sunucusunun çalışır durumda kalmasını sağlamak için otomatik testler içerir:

• 🔄 Otomatik Duman Testleri: GitHub Actions aracılığıyla her 3 günde bir kapsamlı bir duman testi çalıştırılır
• 🚨 Sorun Oluşturma: Başarısız testler, ayrıntılı hata ayıklama bilgileri içeren GitHub sorunlarını otomatik olarak oluşturur
• ⚡ Hızlı CI: Bağımlılıkların hızlı kurulumu ve testler için önbelleğe alma özelliğiyle UV kullanılır
• 🧪 Elle Test: Duman testini yerel olarak uv run scripts/test_mcp_server.py server/zenml_server.py kullanarak çalıştırabilirsiniz

Otomatik testler şunları doğrular:

• MCP protokolü bağlantısı ve el sıkışması
• Sunucu başlatma ve araç keşfi
• Temel araç işlevselliği (ZenML sunucusuna erişilebildiğinde)
• Kaynak ve istem numaralandırması
• diagnose_zenml_setup, kısıtlı ortamlarda bile yapılandırılmış tanılama bilgileri döndürür

Kimlik bilgisi gerektirmeyen CI, MCP protokolü üzerinden her bağdaştırıcıyı kapsar. PR ve sürüm CI süreçleri ayrıca loopback adresinde yeni bir ZenML 0.97.0 OSS sunucusu başlatır ve kalıcı CRUD ile aynı adlı proje yalıtımı makbuzlarını çalıştırır. Sunucu, iş sona erdiğinde kaldırılan geçici bir yapılandırma ve veritabanı kullanır; depo ortamı, kendi barındırdığı bir çalıştırıcı veya ZenML kimlik bilgisi gerekmez.

ZenML'in yerel OSS sunucusunda kimlik doğrulama devre dışıdır ve SQL deposu iş hattı yeniden oynatmayı veya harici dağıtım altyapısını desteklemez. Bu nedenle kısıtlı erişim ve özellik etkinleştirilmiş tetikleyici, yeniden oynatma, dağıtım, bekleme koşulu ve kaynak isteği makbuzları ayrı, isteğe bağlı geçitler olarak kalır. Bunlar sırasıyla ZENML_MCP_RESTRICTED_INTEGRATION=1 ile ZENML_MCP_RESTRICTED_API_KEY veya ZENML_MCP_ACTION_INTEGRATION=1 ile ZENML_MCP_ACTION_FIXTURE içindeki tam geçici fikstür UUID'lerini gerektirir. Geçit nedeniyle atlanan bir test, bu özelliklerin başarıyla test edildiğinin kanıtı değildir. Bir operatör, eksik bir isteğe bağlı geçidi hataya dönüştürmek için ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 ayarlayabilir. Bulut altyapısının sağlanması hiçbir zaman varsayılan test çalıştırmasının parçası değildir.

MCP Inspector ile Hata Ayıklama

Etkileşimli hata ayıklama için MCP Inspector kullanın — MCP araçlarını gerçek zamanlı olarak test etmenizi sağlayan web tabanlı bir araç:

# 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

Bu işlem, kimlik bilgileriniz önceden doldurulmuş bir web arayüzü açar — Connect'e tıklamanız ve herhangi bir aracı etkileşimli olarak test etmek için Tools sekmesini kullanmanız yeterlidir.

Daha ayrıntılı hata ayıklama yönergeleri için CLAUDE.md dosyasına bakın.

Gizlilik ve Analiz

ZenML MCP Server, ürünü geliştirmemize yardımcı olmak için anonim kullanım analizleri toplar.

İzlediklerimiz:

• Hangi araçların ne sıklıkta kullanıldığı
• Hata oranları ve türleri (yalnızca hata türü, mesajlar değil)
• Temel ortam bilgileri (işletim sistemi, Python sürümü ve Docker/CI içinde çalışıp çalışmadığı)
• Oturum süresi ve araç kullanım kalıpları

Toplamadıklarımız:

• ZenML sunucunuzun URL'si veya API anahtarı
• İş hattı adları, model adları veya herhangi bir iş verisi
• Hata mesajları veya yığın izleri
• Kişisel olarak tanımlanabilir hiçbir bilgi

Analizleri devre dışı bırakmak için:

# Option 1
export ZENML_MCP_ANALYTICS_ENABLED=false

# Option 2
export ZENML_MCP_DISABLE_ANALYTICS=true

Hata ayıklama/test için (gönderim yapmak yerine olayları stderr'e kaydeder):

export ZENML_MCP_ANALYTICS_DEV=true

Docker kullanıcıları için: Kapsayıcı yeniden başlatmaları arasında tutarlı bir anonim kimlik kullanmak için ZENML_MCP_ANALYTICS_ID (geçerli bir UUID olmalıdır) ayarlayabilirsiniz. Bunu ayarlamazsanız ve kapsayıcı dosya sistemi analiz kimliği dosyasını kalıcı olarak saklayamazsa, sunucu ZENML_STORE_URL karmasından türetilen deterministik bir anonim UUID'ye geri döner (URL'nin kendisi hiçbir zaman olay özelliği olarak gönderilmez).

Ek analiz seçenekleri:

• ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S — kapanış sırasında analizleri eşzamanlı olarak göndermek için azami süre (saniye; varsayılan: 1.0)

Kapanış izleme hakkında not: Kapanış olayları, teslimat güvenilirliğini artırmak için sınırlı bir zaman aşımıyla eşzamanlı olarak gönderilir. Ancak bir kapsayıcı SIGKILL ile sonlandırılırsa (ör. docker kill), kapanış işleyicileri çalışamaz — bu bir hata değil, Docker/işletim sistemi sınırlamasıdır.

Başlangıç Doğrulaması

Hafif bir başlangıç tanılama denetimini etkinleştirebilirsiniz:

# 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

Bunu ortam değişkeniyle de ayarlayabilirsiniz: ZENML_MCP_STARTUP_VALIDATION=warn.

diagnose_zenml_setup aracı, çalışma zamanı sorunlarını gidermek için MCP aracı olarak da kullanılabilir — ZenML SDK yüklü olmasa veya ortam değişkenleri eksik olsa bile çalışır.

Elle Kurulum

Ön Koşullar

Dağıtılmış bir ZenML sunucusuna erişiminiz olmalıdır. Henüz bir sunucunuz yoksa ZenML Pro üzerinden ücretsiz deneme hesabı açabilirsiniz; dağıtımı sizin için biz yönetiriz.

İpucu: Bir ZenML sunucunuz olduğunda, en kolay kurulum deneyimi için panonuzdaki MCP Settings sayfasına göz atın.

Uyumluluk: Geçerli sürüm ZenML 0.97.0 ile test edilmiştir. Daha eski bir ZenML sürümü kullanıyorsanız bu MCP sunucusunun önceki bir sürümünü kullanın.

Ayrıca yerel olarak uv kurulu olmalıdır (muhtemelen). Daha fazla bilgi için uv belgelerine bakın. Yükleyici betiğiyle veya Mac kullanıyorsanız brew aracılığıyla kurmanızı öneririz. (Teknik olarak buna ihtiyacınız yoktur, ancak kurulum ve yapılandırmayı kolaylaştırır.)

Bu depoyu yerel bir konuma klonlamanız da gerekir:

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

MCP yapılandırma dosyanız

MCP yapılandırma dosyası, MCP istemcisine MCP sunucunuza nasıl bağlanacağını bildiren bir JSON dosyasıdır. Farklı MCP istemcileri bunu farklı şekillerde kullanır veya belirtir. Yaygın olarak kullanılan iki MCP istemcisi Claude Desktop ve Cursor'dır; bunlar için aşağıda kurulum yönergeleri sunuyoruz.

ZenML MCP sunucunuzu aşağıdaki biçimde belirtmeniz gerekir:

{
    "mcpServers": {
        "zenml": {
            "command": "/usr/local/bin/uv",
            "args": ["run", "path/to/server/zenml_server.py"],
            "env": {
                "LOGLEVEL": "WARNING",
                "NO_COLOR": "1",
                "ZENML_LOGGING_COLORS_DISABLED": "true",
                "ZENML_LOGGING_VERBOSITY": "WARN",
                "ZENML_ENABLE_RICH_TRACEBACK": "false",
                "ZENML_MCP_PROFILE": "compact",
                "ZENML_MCP_WRITE_POLICY": "read_write",
                "PYTHONUNBUFFERED": "1",
                "PYTHONIOENCODING": "UTF-8",
                "ZENML_STORE_URL": "https://your-zenml-server-goes-here.com",
                "ZENML_STORE_API_KEY": "your-api-key-here"
            }
        }
    }
}

ZENML_STORE_API_KEY sağlandığında MCP sunucusu, ZenML kimlik bilgilerini bellekte tutar ve zenml login tarafından kaydedilen kimlik bilgilerini okumaz veya güncellemez. Bu durum doğrudan Python çalıştırmaları, MCPB uzantıları ve Docker için geçerlidir. API anahtarı olmayan bağlantılar, kayıtlı terminal oturum açma bilgilerinizi kullanmaya devam edebilir. API anahtarını değiştirdikten sonra MCP sunucusunu yeniden başlatın; yalnızca yeni bir sohbet başlatmak, çalışan sunucu sürecini yeniden kullanabilir.

Değiştirmeniz gereken dört örnek değer vardır:

• yerel olarak kurulu uv dosyasının yolu (yukarıda listelenen yol, brew aracılığıyla kurduysanız Mac'teki yoludur)
• zenml_server.py dosyasının yolu (MCP sunucusuna bağlandığınızda çalıştırılacak dosya budur). Bu dosya, deponun kök dizininde bulunur. Dosyanın tam yolunu belirtmeniz gerekir.
• ZenML sunucusu URL'si (ZenML sunucunuzun URL'sidir. Bunu ZenML Cloud kullanıcı arayüzünde bulabilirsiniz). Şuna benzer: https://d534d987a-zenml.cloudinfra.zenml.io.
• ZenML sunucusu API anahtarı (ZenML sunucunuzun API anahtarıdır. Bunu ZenML Cloud kullanıcı arayüzünde bulabilir veya nasıl oluşturacağınızı öğrenmek için https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account okuyabilirsiniz. ZenML MCP Server için bir hizmet hesabı kullanmanızı öneririz.)

MCP sunucusu Python dosyasını çalıştırma biçimini değiştirebilirsiniz; ancak ortamı ve bağımlılık kurulumunu sizin için yönettiğinden uv muhtemelen en kolay seçenektir.

Claude Desktop ile kullanım için kurulum

Hızlı alternatif: Önceden yapılandırılmış kurulum yönergeleri ve Claude Desktop için derin bağlantılar almak üzere ZenML panonuzdaki MCP Settings sayfasını (Settings → MCP) kullanın.

Claude Desktop uygulamasının en son sürümünün kurulu olması gerekir.

Settings menüsünü açıp bu deponun kök dizinindeki mcp-zenml.mcpb dosyasını menüye sürüklemeniz yeterlidir; kurulum ve yapılandırma sürecinde size yol gösterir. ZenML sunucusu URL'nizi ve API anahtarınızı eklemeniz gerekir.

Not: MCP paketleri (.mcpb), eski Desktop Extensions (.dxt) biçiminin yerini alır; mevcut .dxt dosyaları Claude Desktop'ta çalışmaya devam eder.

İsteğe bağlı: ZenML Araç Çıktılarının Görüntülenmesini İyileştirme

ZenML araç sonuçlarını daha iyi görüntülemek için Claude'u JSON yanıtlarını daha okunabilir bir biçimde gösterecek şekilde yapılandırabilirsiniz. Claude Desktop'ta Settings → Profile bölümüne gidin ve "What personal preferences should Claude consider in responses?" kısmına aşağıdakine benzer bir metin ekleyin (veya bu ifadeleri aynen kullanın!):

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!

Bu, Claude'un ZenML araç çıktılarındaki bilgileri okumayı ve anlamayı çok daha kolaylaştıran Markdown tabloları biçiminde sunmasını sağlar.

Cursor ile kullanım için kurulum

Hızlı alternatif: ZenML panonuzdaki MCP Settings sayfası (Settings → MCP), kimlik bilgileriniz önceden doldurulmuş tam mcp.json içeriğini oluşturabilir.

Cursor uygulamasının kurulu olması gerekir.

Cursor, yapılandırma dosyasını depo başına belirtmeniz bakımından Claude Desktop'tan biraz farklı çalışır. Bu, ZenML MCP sunucusunu birden fazla depoda kullanmak istiyorsanız yapılandırma dosyasını her birinde belirtmeniz gerektiği anlamına gelir.

Tek bir depo için kurulum yapmak üzere:

• deponuzun kök dizininde bir .cursor klasörü oluşturun
• bu klasörün içinde, yukarıdaki içeriğe sahip bir mcp.json dosyası oluşturun
• Cursor ayarlarına gidip ZenML sunucusunu 'etkinleştirmek' için tıklayın.

Deneyimlerimize göre, bazen çalışıyor olmasına rağmen kırmızı bir hata göstergesi görüntüleniyor. Cursor sohbet penceresinde sohbet ederek deneyebilirsiniz. ZenML araçlarına erişip erişemediğini size bildirir.

Docker Görüntüsü

Sunucuyu Docker kapsayıcısı olarak çalıştırabilirsiniz. Süreç stdio üzerinden iletişim kurar, bu nedenle bir MCP istemcisi bağlantısı bekler. ZenML kimlik bilgilerinizi ortam değişkenleri aracılığıyla iletin.

Önceden Oluşturulmuş Görüntüler (Docker Hub)

En son çoklu mimari görüntüyü çekin:

docker pull zenmldocker/mcp-zenml:latest

Sürümlenmiş yayınlar X.Y.Z olarak etiketlenir:

docker pull zenmldocker/mcp-zenml:2.0.0

ZenML kimlik bilgilerinizle çalıştırın (stdio modu):

docker run -i --rm \
  -e ZENML_STORE_URL="https://your-zenml-server.example.com" \
  -e ZENML_STORE_API_KEY="your-api-key" \
  zenmldocker/mcp-zenml:latest

Docker kullanan standart MCP yapılandırması

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

Yerel Olarak Oluşturma

Deponun kök dizininden:

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

Yerel olarak oluşturulmuş görüntüyü çalıştırın:

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

Bu proje, Anthropic'in Desktop Extensions (DXT) biçiminin halefi olan MCP Paketlerini (.mcpb) kullanır. MCP Paketleri, bir MCP sunucusunun tamamını (bağımlılıklar dâhil) kullanıcı dostu yapılandırmayla tek bir dosyada paketler.

Yeniden adlandırma notu: MCP Paketleri, eski .dxt biçiminin yerini alır. Claude Desktop mevcut .dxt dosyalarıyla geriye dönük uyumluluğunu korur; ancak artık mcp-zenml.mcpb dağıtıyor ve bundan sonra bunu kullanmanızı öneriyoruz.

Depo kökündeki mcp-zenml.mcpb dosyası, MCPB 0.4 UV çalışma zamanını kullanır. Ana makine, geçerli işletim sistemi için sabitlenmiş Python bağımlılıklarını kurar; böylece aynı paket, platforma özgü yerel uzantılar içermeden macOS, Windows ve Linux'ta çalışır. UV'nin paketlenmiş ortamı ilk kez çözümlerken ağ erişimine ihtiyacı vardır. Paket derlemeleri, commit edilmiş mcpb-uv.lock öğesini yeniden kullanır ve Python bağımlılık grafiğini çevrimdışı modda çözümler. Paketin bağımlılık listesi, pyproject.toml içindeki [project].dependencies öğesinden alınır. Bu listeyi değiştirdikten sonra, hâlâ uyumlu olan tüm sabitlenmiş sürümleri koruyarak çevrimiçi yeniden çözümleme yapmak için MCPB_REFRESH_LOCK=1 öğesini ayarlayın; MCPB_REFRESH_LOCK=upgrade ise tüm sabitlenmiş sürümleri en yeni sürümlerine yükseltir.

.mcpb dosyasını Claude Desktop ayarlarına sürükleyip bıraktığınızda, aşağıdakiler otomatik olarak gerçekleştirilir:

• Çalışma zamanı bağımlılıklarının kurulumu
• Güvenli yapılandırma yönetimi
• Platformlar arası uyumluluk
• Kullanıcı dostu kurulum süreci

Daha fazla bilgi için Anthropic'in Desktop Extensions (DXT) duyurusuna ve belgelerindeki ilgili MCP paketleme yönergelerine bakın: https://www.anthropic.com/engineering/desktop-extensions

Anthropic MCP Registry'de yayımlandı

Bu MCP sunucusu, resmî Anthropic MCP Registry'de yayımlanır ve uyumlu ana makineler tarafından keşfedilebilir. Her etiketli sürümde CI'ımız, GitHub OIDC kullanarak kayıt girdisini Registry'nin mcp-publisher CLI aracı üzerinden günceller. Böylece ZenML MCP Server'ı, Registry'nin desteklendiği her yerde (ör. Claude Desktop'ın Extensions kataloğunda) doğrudan kurabilir veya keşfedebilirsiniz.

• Her zaman güncel: kayıt girdisi, her sürümde etiketli commit'in manifest.json ve server.json öğeleriyle yenilenir.
• Alternatif kurulum yolları: yerel olarak paketlenmiş .mcpb paketiyle (yukarıya bakın) kurabilir veya Docker imajını çalıştırabilirsiniz.

Registry hakkında daha fazla bilgi:

• Anthropic MCP Registry (topluluk deposu): https://github.com/modelcontextprotocol/registry