ZenML

ZenML için MCP Sunucusu

Bu proje, ZenML API'si ile etkileşim kurmak için bir https://modelcontextprotocol.io/introduction sunucusu uygular.

MCP Nedir?

Model Context Protocol (MCP), uygulamaların Büyük Dil Modellerine (LLM'ler) bağlam sağlama biçimini standartlaştıran açık bir protokoldür. "Yapay zeka uygulamaları için USB-C bağlantı noktası" gibi çalışır; yapay zeka modellerini farklı veri kaynaklarına ve araçlara bağlamak için standart bir yol sağlar.

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 birebir bağlantı kuran 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 erişilebilen harici sistemler

ZenML Nedir?

ZenML, makine öğrenimi ve yapay zeka hatları oluşturmak ve yönetmek için açık kaynaklı bir platformdur. Verileri, modelleri ve deneyimleri yönetmek için birleşik bir arayüz sağlar.

Daha fazla bilgi için ZenML web sitesine ve dokümantasyonumuza bakın.

Özellikler

Sunucu, ZenML sunucusundan temel okuma işlevlerine erişmek için MCP araçları sağlar ve aşağıdakiler hakkında canlı bilgi edinmenin bir yolunu sunar:

Temel Varlıklar

• Kullanıcılar - kullanıcı hesapları ve izinler
• Yığınlar - altyapı yapılandırmaları
• Yığın Bileşenleri - bireysel yığın yapı taşları
• Çeşniler - mevcut bileşen türleri
• Hizmet Bağlayıcıları - bulut kimlik doğrulaması

Hat Yürütme

• Hatlar - hat tanımları
• Hat Çalıştırmaları - yürütme geçmişi ve durumu
• Hat Adımları - bireysel adım ayrıntıları, kod ve günlükler
• Zamanlamalar - otomatik çalıştırma zamanlamaları
• Yapıtlar - veri yapıtları hakkında meta veriler (verinin kendisi değil)

Dağıtım ve Sunum

• Anlık Görüntüler - dondurulmuş hat yapılandırmaları ("ne çalıştırılacağı/sunulacağı" yapıtı)
• Dağıtımlar - durum, URL ve günlüklerle birlikte çalışma zamanı sunum örnekleri
• Hizmetler - model sunum uç noktaları

Organizasyon ve Keşif

• Projeler - ZenML kaynakları için organizasyonel kapsayıcılar
• Etiketler - keşif için çapraz kesen meta veri etiketleri
• Derlemeler - görüntü ve kod bilgisi içeren hat 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)

• Hat çalıştırma şablonları ZenML 0.97.0'da kullanılabilir durumda kalırken, yeni iş akışları için Anlık Görüntüler tercih edilir (bkz. Geçiş Rehberi)

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

Not: Bu entegrasyonu kullanıcı geri bildirimlerine dayalı olarak sürekli iyileştiriyoruz. Deneyiminizi paylaşmak ve daha da iyi hale getirmemize yardımcı olmak için lütfen Slack topluluğumuza katılın!

Araç profilleri ve yazma politikası

Varsayılan compact profili 16 araç tanıtır. Yedi genel araç, kaynak kataloğunu, okumaları, sıradan değişiklikleri ve sınırlı yaşam döngüsü eylemlerini kapsar:

Araç	Amaç
zenml_describe_resources	Desteklenen kaynak türlerini ve sınırlı işlem şemalarını keşfedin
zenml_list_resources	Doğrulanmış filtreler ve sayfalama ile bir kaynak türünü listeleyin
zenml_get_resource	Gerektiğinde üst ve proje kapsamıyla tek bir kaynak alın
zenml_create_resource	Yazılan bir yükten desteklenen bir kaynak oluşturun
zenml_update_resource	Tam olarak bir kaynak UUID'sini güncelleyin
zenml_delete_resource	Tam olarak bir kaynak UUID'sini silin veya arşivleyin
zenml_action_resource	Yeniden deneme olmadan beyaz listeye alınmış bir yaşam döngüsü veya ilişki eylemi çalıştırın

Dokuz odaklanmış araç, teşhis, aktif bağlam, akışı yapılan günlükler veya kod, hat yürütme veya etkileşimli bir Uygulama sağladıkları için kalır:

• 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, bir possibly_truncated bayrağıyla ve hangi girdilerin eksik olduğunu ve nedenini söyleyen bir note ile döndürür. Yalnızca en yeni girdileri almak için tail değerini geçirin. ZenML 0.97+ sunucularında günlük deposunda sayfalama yapar; 0.96'da eski tek istekli uç noktayı kullanır.

Mevcut bir istemci hâlâ list_pipeline_runs gibi eski varlığa özgü adlara bağımlı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ümleri için destek eklemez. Yalnızca geçiş sırasında kullanın: eski yanıt biçimleri, kompakt araçlardan daha fazla operasyonel meta veri açığa çıkarabilir, ancak sunucu her iki profilde de kimlik bilgisi taşıyan yapılandırmayı ve diğer hassas alanları atlar.

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

Profil	Politika	Tanıtılan 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 tamamı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 ayrıca oluşturma, güncelleme, silme ve eylem şemalarını da atlar. Daha eski ZENML_MCP_READ_ONLY=true ayarı kabul edilmeye devam eder; geçersiz politika değerleri salt okunur moda kapanır. Geçersiz bir ZENML_MCP_PROFILE, yapılandırma hatasıyla başlatmayı durdurur.

Sürüm 2.0.0, MCP Python SDK 2.2.0 ve ZenML 0.96.4 gerektirir. Kompakt profil yeni varsayılandır ve varlığa özgü araç adlarını çağıran istemciler için bozucu bir keşif değişikliğidir. 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ı ayırt eder. Sunucu, bir değişiklik ZenML'e ulaşmış olabilecekten sonra yeniden denemez. Kabul edilen veya bilinmeyen bir sonuç için, tekrar çağırıp çağırmamaya karar vermeden önce yanıttaki mutabakat talimatlarını izleyin. Mevcut olduğunda adlandırılmış okumayı kullanın. Webhook oluşturma ve gizli anahtar döndürme, yeni bir imzalama anahtarını bir kez döndürebilir; sonraki okumalar bunu atlar. Silme şemaları, bir işlemin meta verileri arşivleyip arşivlemediğini, meta verileri kaldırıp kaldırmadığını, canlı bir kaynağın sağlanmasını kaldırıp kaldırmadığını veya depolanan yapıt verilerini silebilip silemeyeceğini belirtir.

İlk 2.0 sürümü, projeler, yığınlar ve bileşenler, çeşniler, hizmetler, 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 kanca çağrıları için sıradan işlemleri kapsar. Kullanıcılar, zamanlamalar, hizmet bağlayıcı türleri, gizli anahtarlar ve kaynak istekleri, zenml_describe_resources tarafından 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 anahtar değeri CRUD'unu, bağlayıcı oturum açma ve doğrulamasını, ham webhook olaylarını ve toplu hata ayıklama veya soy araçlarını hariç tutar.

Genel bir iş akışına, kesin şemayı keşfederek başlayın, ardından onu ç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 durumda kalır. Analiz istemleri, sınırlı kaynak şeması uç noktaları ve most_recent_runs, araçlar yerine 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. Hat kolaylığı oluşturma ve şablon tabanlı tetikleyici parametresi kullanımdan kaldırılmıştır. Eski profilde, get_run_template ve list_run_templates mevcut istemciler için kullanılabilir durumda kalır.

Eski tag girdisi, şema uyumluluğu için list_run_templates içinde kalır, ancak ZenML 0.97.0'da eşdeğer sunucu tarafı filtre yoktur. Null olmayan bir değer, SDK çağrısından önce reddedilir. Anlık görüntü etiketi filtrelemesi kullanılabilir durumda kalır.

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

Değişiklik neden? Anlık görüntüler, çalıştırma şablonlarının yerini ZenML'in tercih edilen çalıştırılabilir hat yapıtı olarak aldı. 0.97.0 SDK'sı hâlâ çalıştırma şablonu CRUD'unu desteklerken, yeni kod anlık görüntüleri kullanmalıdır.

Hızlı Geçiş Rehberi

Eski Desen (Şablonlar)	Kompakt Desen (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ışı (Anlık Görüntü Öncelikli)

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)

Not: get_deployment_logs sınırlı çıktı döndürür (varsayılan 100 satır, maksimum 1000, 100KB ile sınırlı) ve uygun dağıtıcı entegrasyonunun kurulu olmasını gerektirir.

Kontrol Paneli Üzerinden Hızlı Kurulum (Önerilen)

ZenML MCP Sunucusunu kurmanın en kolay yolu, ZenML kontrol panelinizdeki MCP Ayarları sayfasıdır.

ZenML kontrol panelinizde Ayarlar → MCP bölümüne giderek şunları elde edin:

• Belirli sunucu URL'niz ve kimlik bilgileriniz için ö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 Ayarları sayfası, tek tıklamayla bir 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 dahil edilir.

ZenML OSS Kullanıcıları

1. Önce Ayarlar → Hizmet Hesapları aracılığıyla bir hizmet hesabı belirteci oluşturun
2. Belirteci MCP Ayarları sayfasına yapıştırın
3. IDE'niz için oluşturulan yapılandırmayı kopyalayın

---

Manuel kurulumu mu tercih edersiniz? Aşağıdaki ayrıntılı talimatlara bakın.

MCP Uygulamaları (Deneysel)

MCP Uygulamaları nedir? MCP Uygulamaları, MCP sunucularının doğrudan yapay zeka istemcilerine sunabileceği etkileşimli HTML arayüzleridir. Korumalı iframe'lerde işlenirler ve sunucu araçlarını çift yönlü olarak çağırabilirler. Tam ayrıntılar için resmi duyuruya bakın.

Bu sunucu iki deneysel MCP Uygulaması içerir:

Uygulama	Araç	Açıklama
Hat Çalıştırmaları Kontrol Paneli	open_pipeline_run_dashboard	Durum, adım ayrıntıları ve günlüklerle son hat çalıştırmalarının etkileşimli tablosu
Çalıştırma Etkinlik Grafiği	open_run_activity_chart	Durum dökümüyle son 30 günün hat çalıştırma etkinliğinin çubuk grafiği

Bu uygulamalar kavram kanıtı örnekleri olarak dahil edilmiştir. Daha fazla MCP Uygulaması için geri bildirim ve katkıları memnuniyetle karşılıyoruz. Bu yeni özellik için henüz erken günler, bu yüzden nasıl gelişeceğini görmemiz gerekecek. Gelecekte daha tam olarak desteklemeyi bekliyoruz.

Desteklenen İstemciler

MCP Uygulamaları Streamable HTTP aktarımı gerektirir (stdio değil). Aşağıdaki istemciler şu anda MCP Uygulamalarını destekler:

• ✅ VS Code (Insiders Sürümü)
• ✅ Goose
• ✅ ChatGPT (yakında başlatılıyor)
• ⚠️ Claude Desktop -- Ocak 2026 sonu itibarıyla Uygulamaları henüz işlemiyor.
• ⚠️ Claude.ai (web) — Ocak 2026 sonu itibarıyla Uygulamaları henüz işlemiyor.

Not: Bu yazının yazıldığı sırada Claude Desktop veya Claude.ai ile kapsamlı test yapamadık. Sorunlarla karşılaşırsanız lütfen bildirin.

MCP Uygulamalarını Docker ile Çalıştırma

MCP Uygulamaları Streamable HTTP kullanır. Kapsayıcı bağlantı noktasını geri döngüye bağlı tutun ve uzaktan erişime izin vermeden önce önüne kimliği doğrulanmış bir ters proxy veya kimlik farkında erişim hizmeti koyun. Ana bilgisayar ve Kaynak doğrulaması, DNS yeniden bağlamaya karşı korur; ç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ış uzaktan erişimi yapılandırın: Adlandırılmış bir Cloudflare Tunnel, erişim kontrolleriyle Tailscale Funnel veya eşdeğer kimlik doğrulamalı bir ters proxy oluşturun. Özel kaynağını http://127.0.0.1:8001 adresine yönlendirin, genel ana bilgisayar adı için bir kimlik veya hizmet kimlik bilgisi gerektirin ve yalnızca kimliği doğrulanmış istekleri kaynağa iletin. MCP istemcinizi sağlayıcının desteklediği OAuth akışını veya yetkilendirme başlıklarını 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. Bir JSON-RPC veya MCP yanıtı, çevrenin açık olduğu ve önce düzeltilmesi gerektiği anlamına gelir.

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

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

• Yapay zekadan "pipeline çalıştırma panelini aç" veya "çalıştırma etkinlik grafiğini göster" demesini isteyin

Önemli notlar:

• ZENML_ACTIVE_PROJECT_ID gereklidir — bu olmadan, pipeline çalıştırma araçları "No project is currently set as active" hatasıyla başarısız olur
• --disable-dns-rebinding-protection yalnızca kimliği doğrulanmış proxy genel ana bilgisayarı doğruladığında ve kapsayıcı bağlantı noktası yalnızca geri döngü (loopback) olarak kaldığında uygundur
• ZenML API anahtarını MCP istemcisinin ihtiyaç duyduğu izinlerle sınırlandırın; yalnızca inceleme amaçlı istemciler için ZENML_MCP_WRITE_POLICY=read_only kullanın

Test ve Kalite Güvencesi

Bu proje, MCP sunucusunun işlevsel 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ışır
• 🚨 Sorun Oluşturma: Başarısız testler, ayrıntılı hata ayıklama bilgileriyle otomatik olarak GitHub sorunları oluşturur
• ⚡ Hızlı CI: Hızlı bağımlılık kurulumu ve testi için önbelleğe alma ile UV kullanır
• 🧪 Manuel 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ışma
• Sunucu başlatma ve araç keşfi
• Temel araç işlevselliği (ZenML sunucusuna erişilebildiğinde)
• Kaynak ve istem numaralandırma
• diagnose_zenml_setup kısıtlı ortamlarda bile yapılandırılmış tanılama döndürür

Kimlik bilgisi gerektirmeyen CI, MCP protokolü aracılığıyla her bağdaştırıcıyı kapsar. PR ve sürüm CI'si ayrıca geri döngü adresinde yeni bir ZenML 0.97.0 OSS sunucusu başlatır ve kalıcı CRUD ve aynı adlı proje yalıtım makbuzlarını çalıştırır. Sunucu, iş çıktığında kaldırılan geçici bir yapılandırma ve veritabanı kullanır; depo ortamı, kendi kendine barındırılan çalıştırıcı veya ZenML kimlik bilgisi gerekmez.

ZenML'nin yerel OSS sunucusu kimlik doğrulamayı devre dışı bırakır ve SQL deposu pipeline tekrarını veya harici dağıtım altyapısını desteklemez. Kısıtlı erişim ve özellik etkin tetikleyici, tekrar, dağıtım, bekleme koşulu ve kaynak isteği makbuzları bu nedenle ayrı isteğe bağlı katılım kapıları 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 tek kullanımlık fikstür UUID'lerini gerektirir. Kapılı bir atlama, bu yeteneklerin geçtiğinin kanıtı değildir. Bir operatör, eksik bir isteğe bağlı katılım kapısını hataya dönüştürmek için ZENML_MCP_REQUIRE_COMPLETE_INTEGRATION=1 ayarlayabilir. Bulut altyapısı sağlama, varsayılan test çalıştırmasının asla bir parçası değildir.

MCP Inspector ile Hata Ayıklama

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

# 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, kimlik bilgileriniz önceden doldurulmuş bir web arayüzü açar — sadece Connect düğmesine tıklayın ve herhangi bir aracı etkileşimli olarak test etmek için Tools sekmesini kullanın.

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

Gizlilik ve Analitik

ZenML MCP Sunucusu, ürünü iyileştirmemize yardımcı olmak için anonim kullanım analitiği toplar.

Şunları takip ediyoruz:

• Hangi araçların kullanıldığı ve ne sıklıkta kullanıldığı
• Hata oranları ve türleri (yalnızca hata türü, mesaj yok)
• Temel ortam bilgileri (OS, Python sürümü ve Docker/CI içinde çalışıp çalışmadığı)
• Oturum süresi ve araç kullanım modelleri

Şunları toplamıyoruz:

• ZenML sunucu URL'niz veya API anahtarınız
• Pipeline adları, model adları veya herhangi bir iş verisi
• Hata mesajları veya yığın izleri
• Kişisel olarak tanımlanabilir herhangi bir bilgi

Analitiği 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öndermek yerine olayları stderr'e kaydeder):

export ZENML_MCP_ANALYTICS_DEV=true

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

Ek analitik seçenekleri:

• ZENML_MCP_ANALYTICS_SHUTDOWN_TIMEOUT_S — kapanış sırasında analitiği senkron olarak boşaltmak için maksimum süre (saniye) (varsayılan: 1.0)

Kapanış takibi hakkında not: Kapanış olayları, en iyi teslimat güvenilirliği için sınırlı bir zaman aşımıyla senkron olarak gönderilir. Ancak, bir kapsayıcı SIGKILL ile öldürülürse (örn. docker kill), kapanış işleyicileri tetiklenemez — bu bir Docker/OS sınırlamasıdır, bir hata değildir.

Başlangıç Doğrulaması

Hafif bir başlangıç tanılama kontrolü 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şkeni aracılığıyla da ayarlayabilirsiniz: ZENML_MCP_STARTUP_VALIDATION=warn.

diagnose_zenml_setup aracı, çalışma zamanı sorun giderme için bir MCP aracı olarak da kullanılabilir — ZenML SDK kurulu olmasa veya ortam değişkenleri eksik olsa bile çalışır.

Manuel Kurulum

Ön Koşullar

Dağıtılmış bir ZenML sunucusuna erişiminiz olması gerekir. Yoksa, ZenML Pro adresinde ücretsiz deneme için kaydolabilirsiniz ve dağıtımı sizin için biz yönetiriz.

İpucu: Bir ZenML sunucunuz olduğunda, en kolay kurulum deneyimi için panelinizdeki MCP Ayarları 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ü çalıştırıyorsanız, lütfen bu MCP sunucusunun daha eski bir sürümünü kullanın.

Ayrıca (muhtemelen) uv öğesini yerel olarak kurmanız gerekecektir. Daha fazla bilgi için uv belgelerine bakın. Kurulum betikleri veya Mac kullanıyorsanız brew aracılığıyla kurulum yapmanızı öneririz. (Teknik olarak buna ihtiyacınız yok, ancak kurulumu ve yapılandırmayı kolaylaştırır.)

Ayrıca bu depoyu yerel olarak bir yere klonlamanız gerekecektir:

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ı söyleyen bir JSON dosyasıdır. Farklı MCP istemcileri bunu farklı şekilde kullanır veya belirtir. Yaygın olarak kullanılan iki MCP istemcisi Claude Desktop ve Cursor olup, aşağıda kurulum talimatlarını sağlıyoruz.

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

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

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

• yerel olarak kurulu uv yolunuz (yukarıda listelenen yol, brew aracılığıyla kurduysanız bir Mac'te olacağı yerdir)
• zenml_server.py dosyasının yolu (bu, MCP sunucusuna bağlandığınızda çalıştırılacak dosyadır). Bu dosya bu deponun içinde kök dizinde bulunur. Bu dosyanın tam yolunu belirtmeniz gerekecektir.
• ZenML sunucu URL'si (bu, ZenML sunucunuzun URL'sidir. Bunu ZenML Cloud arayüzünde bulabilirsiniz). https://d534d987a-zenml.cloudinfra.zenml.io gibi görünecektir.
• ZenML sunucu API anahtarı (bu, ZenML sunucunuzun API anahtarıdır. Bunu ZenML Cloud arayüzünde bulabilir veya nasıl oluşturulacağına dair https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account okuyabilirsiniz. ZenML MCP sunucusu için bir hizmet hesabı kullanmanızı öneririz.)

MCP sunucusu Python dosyasını çalıştırma şeklinizi değiştirmekte özgürsünüz, ancak uv kullanmak muhtemelen en kolay seçenek olacaktır çünkü ortamı ve bağımlılık kurulumunu sizin için halleder.

Claude Desktop ile kullanım için kurulum

Hızlı alternatif: Önceden yapılandırılmış kurulum talimatları ve Claude Desktop için derin bağlantılar almak için ZenML panelinizdeki MCP Ayarları sayfasını (Ayarlar → MCP) kullanın.

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

Ayarlar menüsünü açıp bu deponun kökündeki mcp-zenml.mcpb dosyasını menüye sürükleyebilirsiniz; kurulum ve yapılandırma sürecinde size rehberlik edecektir. ZenML sunucu URL'nizi ve API anahtarınızı eklemeniz gerekecektir.

Not: MCP paketleri (.mcpb), eski Masaüstü Uzantıları (.dxt) biçiminin yerini alır; mevcut .dxt dosyaları Claude Desktop'ta hâlâ çalışır.

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

ZenML araç sonuçlarıyla daha iyi bir deneyim için Claude'u JSON yanıtlarını daha okunabilir bir biçimde görüntüleyecek şekilde yapılandırabilirsiniz. Claude Desktop'ta Ayarlar → Profil bölümüne gidin ve "What personal preferences should Claude consider in responses?" bölümüne aşağıdakine benzer bir şey ekleyin (veya bu tam kelimeleri 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'u ZenML araç çıktılarını işaretleme tabloları olarak biçimlendirmeye teşvik edecek ve bilgileri okumayı ve anlamayı çok daha kolay hale getirecektir.

Cursor ile kullanım için kurulum

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

Cursor kurulu olması gerekir.

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

Tek bir depo için kurmak üzere şunları yapmanız gerekir:

• deponuzun kökünde bir .cursor klasörü oluşturun
• içinde yukarıdaki içerikle bir mcp.json dosyası oluşturun
• Cursor ayarlarınıza gidin ve 'etkinleştirmek' için ZenML sunucusuna tıklayın.

Deneyimlerimize göre, çalışıyor olsa bile bazen kırmızı bir hata göstergesi gösterir. Cursor sohbet penceresinde sohbet ederek deneyebilirsiniz. ZenML araçlarına erişip erişemediğini size bildirecektir.

Docker Görüntüsü

Sunucuyu bir Docker kapsayıcısı olarak çalıştırabilirsiniz. Süreç stdio üzerinden iletişim kurar, bu nedenle bir MCP istemci 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 çok mimarili görüntüyü çekin:

docker pull zenmldocker/mcp-zenml:latest

Sürümlü sürümler 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 Derleme

Depo kökünden:

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

Yerel olarak derlenen 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, MCP Paketlerini (.mcpb) kullanır — Anthropic'in Masaüstü Uzantılarının (DXT) halefi. MCP Paketleri, tüm bir MCP sunucusunu (bağımlılıklar dahil) 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 uyumlu kalır, ancak artık mcp-zenml.mcpb gönderiyoruz 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 bilgisayar, geçerli işletim sistemi için sabitlenmiş Python bağımlılıklarını kurar, böylece aynı paket platforma özgü yerel uzantılar gömmeden macOS, Windows ve Linux'ta çalışır. Kurulum, UV paketlenmiş ortamı ilk kez çözdüğünde ağ erişimi gerektirir.

Paket derlemeleri, kaydedilmiş mcpb-uv.lock dosyasını yeniden kullanır ve Python bağımlılık grafiğini çevrimdışı modda çözer. Paketin bağımlılık listesi, pyproject.toml içindeki [project].dependencies dosyasından gelir. Bu listeyi değiştirdikten sonra, hâlâ uyan her sabitlemeyi korurken çevrimiçi olarak yeniden çözmek için MCPB_REFRESH_LOCK=1 ayarlayın; MCPB_REFRESH_LOCK=upgrade her sabitlemeyi en yeni sürümüne taşır. When you drag and drop the .mcpb file into Claude Desktop's settings, it automatically handles:

• Runtime dependency installation
• Secure configuration management
• Cross-platform compatibility
• User-friendly setup process

For 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-extensions

Anthropic MCP Kayıt Defteri'nde Yayınlandı

Bu MCP sunucusu, resmi Anthropic MCP Kayıt Defteri'nde yayınlanmıştır ve uyumlu ana bilgisayarlar tarafından keşfedilebilir. Her etiketli sürümde, CI'mız, GitHub OIDC kullanarak kayıt defterinin mcp-publisher CLI'si aracılığıyla kayıt defteri girdisini günceller; böylece ZenML MCP Sunucusu'nu kayıt defterinin desteklendiği her yerde (ör. Claude Desktop'un Uzantılar kataloğu) doğrudan kurabilir veya keşfedebilirsiniz.

• Her zaman güncel: kayıt defteri girdisi, etiketli taahhüdün manifest.json ve server.json değerlerinden her sürümde yenilenir.
• Alternatif kurulum yolları: yine de paketlenmiş .mcpb paketi aracılığıyla yerel olarak kurabilir (yukarıya bakın) veya Docker görüntüsünü çalıştırabilirsiniz.

Kayıt defteri hakkında daha fazla bilgi edinin:

• Anthropic MCP Kayıt Defteri (topluluk deposu): https://github.com/modelcontextprotocol/registry