Keboola

Keboola MCP Sunucusu

AI ajanlarınızı, MCP istemcilerini (Cursor, Claude, Windsurf, VS Code ...) ve diğer AI asistanlarını Keboola'ya bağlayın. Verileri, dönüşümleri, SQL sorgularını ve iş tetikleyicilerini açığa çıkarın—yapıştırıcı kod gerekmez. Ajanlara ihtiyaç duydukları anda ve yerde doğru verileri iletin.

Genel Bakış

Keboola MCP Sunucusu, Keboola projeniz ile modern AI araçları arasında açık kaynaklı bir köprüdür. Depolama erişimi, SQL dönüşümleri ve iş tetikleyicileri gibi Keboola özelliklerini Claude, Cursor, CrewAI, LangChain, Amazon Q ve daha fazlası için çağrılabilir araçlara dönüştürür.

• Hızlı Başlangıç
• Yerel Kurulum

Özellikler

AI Ajanı ve MCP Sunucusu ile şunları yapabilirsiniz:

• Depolama: Tabloları doğrudan sorgulayın ve tablo veya bucket açıklamalarını yönetin
• Bileşenler: Extractors, writers, data apps ve dönüşüm konfigürasyonlarını oluşturun, listeleyin ve inceleyin
• SQL: Doğal dil ile SQL dönüşümleri oluşturun
• İşler: Bileşenleri ve dönüşümleri çalıştırın ve iş yürütme ayrıntılarını alın
• Akışlar: Koşullu Akışlar ve Orkestratör Akışlarını kullanarak iş akışı boru hatları oluşturun ve yönetin
• Data Apps: Depolama verileri üzerindeki sorgularınızı görüntüleyen Keboola Streamlit Data Apps oluşturun, dağıtın ve yönetin
• Meta Veri: Doğal dil kullanarak proje dokümantasyonunu ve nesne meta verilerini arayın, okuyun ve güncelleyin
• Geliştirme Dalları: Tüm işlemlerin seçili dala kapsamlandığı üretim dışındaki geliştirme dallarında güvenle çalışın.

---

🚀 Hızlı Başlangıç: Uzaktan MCP Sunucusu (En Kolay Yol)

Keboola MCP Sunucusunu kullanmanın en kolay yolu Uzaktan MCP Sunucumuz üzerindendir. Bu barındırılan çözüm, yerel kurulum, yapılandırma veya yükleme ihtiyacını ortadan kaldırır.

Uzaktan MCP Sunucusu Nedir?

Uzaktan sunucumuz, her çok kiracılı Keboola yığınında barındırılır ve OAuth kimlik doğrulamasını destekler. Uzaktan Streamable HTTP bağlantısını ve OAuth kimlik doğrulamasını destekleyen herhangi bir AI asistanından bağlanabilirsiniz.

Nasıl Bağlanılır

1. Uzaktan sunucu URL'nizi alın: Keboola Proje Ayarlarınıza gidin → MCP Server sekmesi
2. Sunucu URL'sini kopyalayın: https://mcp.<YOUR_REGION>.keboola.com/mcp gibi görünecektir
3. AI asistanınızı yapılandırın: URL'yi AI asistanınızın MCP ayarlarına yapıştırın
4. Kimlik doğrulayın: Keboola hesabınızla giriş yapmanız istenecektir. Hangi proje(ler) üzerinde çalışılacağı daha sonra konuşmada seçilir (ör. "Keboola projelerimi listele" / "X projesini kullan")

Desteklenen İstemciler

• Cursor: Projenizin MCP Sunucu ayarlarındaki "Install In Cursor" düğmesini kullanın veya bu düğmeye tıklayın
• Claude Desktop: Entegrasyonu Ayarlar → Entegrasyonlar üzerinden ekleyin
• Claude Code: claude mcp add --transport http keboola <URL> kullanarak kurun (ayrıntılar için aşağıya bakın)
• Windsurf: Uzaktan sunucu URL'si ile yapılandırın
• Make: Uzaktan sunucu URL'si ile yapılandırın
• Diğer MCP istemcileri: Uzaktan sunucu URL'si ile yapılandırın

Claude Code Kurulumu

Claude Code, terminalinizi kullanarak Claude ile etkileşim kurmanızı sağlayan bir komut satırı arayüzü aracıdır. Keboola MCP Sunucusu entegrasyonunu basit bir komut kullanarak kurabilirsiniz.

Kurulum:

Terminalinizde aşağıdaki komutu çalıştırın, <YOUR_REGION> yerine Keboola bölgenizi yazın:

claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp

Bölgeye özel komutlar:

Bölge	Kurulum Komutu
US Virginia AWS	claude mcp add --transport http keboola https://mcp.keboola.com/mcp
US Virginia GCP	claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp
EU Frankfurt AWS	claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp
EU Ireland Azure	claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp
EU Frankfurt GCP	claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp

Kullanım:

Kurulduktan sonra, Claude Code'da konuşmanıza /mcp yazarak ve kullanmak istediğiniz Keboola araçlarını seçerek Keboola MCP Sunucusunu kullanabilirsiniz.

Kimlik Doğrulama:

Claude Code'da Keboola MCP Sunucusunu ilk kullandığınızda, bir tarayıcı penceresi açılır ve sizden şunları yapmanız istenir:

1. Keboola hesabınızla giriş yapın
2. Bağlantıyı yetkilendirin

Kimlik doğrulamasından sonra, Keboola araçlarını doğrudan Claude Code'dan kullanmaya başlayabilirsiniz. Proje seçimi daha sonra konuşmada yapılır — Claude'a hangi Keboola projesini(lerini) kullanacağını sorun.

Ayrıntılı kurulum talimatları ve bölgeye özel URL'ler için Uzaktan Sunucu Kurulum dokümantasyonumuza bakın.

Geliştirme Dallarını Kullanma

Üretim verilerinizi etkilemeden Keboola geliştirme dallarında güvenle çalışabilirsiniz. Uzaktan barındırılan MCP Sunucuları KBC_BRANCH_ID parametresine saygı gösterir ve tüm işlemleri belirtilen dala kapsamlandırır. Geliştirme dalı kimliğini, kullanıcı arayüzünde geliştirme dalına giderken URL'de bulabilirsiniz, örneğin: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. Dal kimliği, X-Branch-Id: <branchId> başlığı kullanılarak her isteğe dahil edilmelidir, aksi takdirde MCP Sunucusu varsayılan olarak üretim dalını kullanır. Bu, sunucu bağlantısını yöneten AI istemcisi veya ortam tarafından yönetilmelidir.

Araç Yetkilendirme ve Erişim Kontrolü

HTTP tabanlı taşımalar (Streamable HTTP) kullanırken, HTTP başlıklarını kullanarak istemcilerin hangi araçlara erişebileceğini kontrol edebilirsiniz. Bu, AI ajan yeteneklerini kısıtlamak veya uyumluluk politikalarını uygulamak için kullanışlıdır.

Yetkilendirme Başlıkları

Başlık	Açıklama	Örnek
X-Allowed-Tools	Virgülle ayrılmış izin verilen araçlar listesi	get_configs,get_buckets,query_data
X-Disallowed-Tools	Virgülle ayrılmış hariç tutulacak araçlar listesi	create_config,run_job
X-Read-Only-Mode	Yalnızca salt okunur araçlarla sınırla	true, 1 veya yes

Filtre Davranışı

Filtreler şu sırayla uygulanır: izin verilen → salt okunur kesişim → hariç tutulan. Boş başlıklar = kısıtlama yok.

Salt Okunur Araçlar

Salt okunur araçlar, readOnlyHint=True ile işaretlenen araçlardır. Bu araçlar yalnızca bilgi alır ve Keboola projenizde herhangi bir değişiklik yapmaz. Salt okunur araçların güncel listesi için, gerçek araç setinin otomatik oluşturulmuş bir anlık görüntüsü olan TOOLS.md dosyasına bakın.

Örnek: Salt Okunur Erişim

X-Read-Only-Mode: true

Ayrıntılı dokümantasyon için developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control adresine bakın.

---

Yerel MCP Sunucusu Kurulumu (Özel veya Geliştirici Yolu)

Tam kontrol ve kolay geliştirme için MCP sunucusunu kendi makinenizde çalıştırın. Araçları özelleştirmek, yerel olarak hata ayıklamak veya hızlı yineleme yapmak istediğinizde bunu seçin. Sunucuyu kurar, kimlik doğrularsınız (tek seferlik tarayıcı girişi — yapıştırılacak belirteç yok) ve başlatırsınız. Bu yaklaşım maksimum esneklik sunar (özel araçlar, yerel günlükleme, çevrimdışı yineleme) ancak manuel kurulum gerektirir ve güncellemeleri ile sırları kendiniz yönetirsiniz.

Sunucu, sunucuyu başlatırken --transport <transport> argümanı sağlanarak seçilebilen birden fazla taşıma seçeneğini destekler:

• stdio - --transport belirtilmediğinde varsayılandır. Standart giriş/çıkış, genellikle tek bir istemciyle yerel dağıtım için kullanılır.
• streamable-http - Sunucuyu HTTP üzerinden çift yönlü akış kanalıyla uzaktan çalıştırır ve istemci ile sunucunun sürekli mesaj alışverişi yapmasını sağlar. /mcp üzerinden bağlanın (ör. http://localhost:8000/mcp).
• http-compat - Geriye dönük uyumluluk için streamable-http için bir takma addır.

Keboola projenizle çalışmak için sunucunun iki şeye ihtiyacı vardır: Keboola Bölgeniz (KBC_STORAGE_API_URL) ve bir kimlik doğrulama yöntemi. Önerilen yol, tek seferlik tarayıcı girişidir — asla belirteç oluşturmaz, kopyalamaz veya yapıştırmazsınız. İsteğe bağlı olarak bir geliştirme dalında çalışmak için KBC_BRANCH_ID ayarlayın.

Değişkenlerin bazıları istek başlıklarından alınmaz:

• KBC_STORAGE_API_URL: kendi Storage API URL'si ile başlatılan bir sunucu (--api-url parametresi veya KBC_STORAGE_API_URL ortam değişkeni) yalnızca o tek Keboola yığınına hizmet eder. Farklı bir ana bilgisayar isteyen bir X-Storage-Api-Url başlığı yok sayılır (bir uyarı günlüğe kaydedilir) — sunucu istek için kendi URL'sini tutar. Her isteğin kendi yığınını seçmesini istiyorsanız, sunucuyu kendi Storage API URL'si olmadan başlatın.
• KBC_KUBERNETES_TOKEN_PATH (yalnızca dağıtılmış sunucular, bkz. docs/kubernetes-sa-auth.md): yalnızca ortamdan okunur, asla bir başlıktan okunmaz.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: yukarıdaki Storage API URL'si ile aynı fikir — kendi çalışma alanı sabitlemesiyle başlatılan bir sunucu (her iki değişken veya --workspace-id aracılığıyla) her istek için bu sabitlemeyi tutar; farklı bir çalışma alanı isteyen bir X-Workspace-Id veya X-Workspace-Schema başlığı yok sayılır (bir uyarı günlüğe kaydedilir). Kendi sabitlemesi olmayan bir sunucu (paylaşılan çok kullanıcılı durum), aşağıda açıklandığı gibi sabitlemeyi istek başına almaya devam eder.

Giriş Yapma

Tarayıcınızla bir kez oturum açın; sunucu oturumu saklar ve otomatik olarak yeniler, böylece yönetilecek belirteç yoktur:

uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com

Bu, Keboola'ya giriş yapmak için tarayıcınızı açar ve ardından yığın genelindeki oturumu ~/.keboola/mcp/credentials.json konumuna kaydeder (yalnızca sizin tarafınızdan okunabilir, her yığın için bir giriş). Ardından, sunucuyu yalnızca KBC_STORAGE_API_URL ayarlı olarak başlatın — belirteç gerekmez. Hangi proje(ler) üzerinde çalışılacağı, giriş sırasında değil, daha sonra konuşmada seçilir (get_accessible_projects / set_project_scope).

Komut	Ne yapar
login --api-url <url>	Bir yığına giriş yapın
login --force	Tekrar giriş yapın / hesap değiştirin
login --show-token	Geçerli oturum belirtecini yazdırın (hata ayıklama)
logout [--api-url <url>] [--all]	Bir yığın için saklanan oturumu kaldırın (veya tüm yığınlar)

Sunucuyu etkileşimli bir terminalde stdio üzerinden saklanan oturum olmadan başlattığınızda, ilk başlatmada bu tarayıcı girişini otomatik olarak çalıştırır. MCP istemcileri (Claude, Cursor, …) sunucuyu tarayıcının açılamayacağı arka planda başlatır, bu nedenle önce login komutunu kendiniz bir kez çalıştırın.

Keboola hesabı olmadan başlatma

Sunucuyu yalnızca KBC_STORAGE_API_URL ile ve hiçbir kimlik bilgisi olmadan da başlatabilirsiniz. Bootstrap modunda başlar: Keboola erişimi gerektiren araçlar kimlik bilgisinin nasıl alınacağını açıklar ve bir araç kimlik bilgisi olmadan çalışır — create_project. Yeni bir Keboola projesi oluşturur, oturumu projeye kaydeder ve bir onay URL'si döndürür. Bu URL'yi bir tarayıcıda açmak ve giriş yapmak projeyi kalıcı olarak size ait yapar; o zamana kadar geçicidir ve Keboola onu geri alabilir ve onayladığınızda, aracın oluşturduğu oturum iptal edilir ve kendi login ile devam edersiniz.

Bu, ajan sağlama özelliği etkinleştirilmiş bir yığın gerektirir; başka yerlerde araç kullanılamadığını bildirir.

Tarayıcı olmadan kimlik doğrulama

Tarayıcı girişinin mümkün olmadığı konteynerler veya CI için, doğrudan bir Keboola erişim veya kişisel erişim belirteci sağlayın — KBC_STORAGE_TOKEN (env değişkeni) ayarlayın veya X-StorageAPI-Token başlığını gönderin — projeyi seçmek için KBC_PROJECT_ID (veya X-KBC-ProjectId başlığı) ile birlikte. HTTP taşımalarında bunlar istek başına başlık olarak sağlanabilir, böylece her istek kendi kimlik bilgilerini taşır.

KBC_WORKSPACE_ID

Sorguları, yukarıdaki şema tabanlı aramaya kıyasla kimliğine göre belirli, zaten var olan bir çalışma alanına sabitler ve her ikisi de ayarlandığında KBC_WORKSPACE_SCHEMA üzerinde öncelik alır. Bu, bir Data App / kai-agent çağıranının X-Workspace-Id başlığı olarak sağladığı seçenektir, böylece o uygulamaya gömülü Kai yalnızca kendi çalışma alanı üzerinden sorgular.

KBC_WORKSPACE_ID ortam değişkeni, --workspace-id CLI bayrağı veya (istek başına, çok kullanıcılı dağıtımlar için) X-Workspace-Id başlığı aracılığıyla ayarlayın.

KBC_STORAGE_API_URL (Keboola Bölgesi)

Keboola Bölge API URL'niz dağıtım bölgenize bağlıdır. Keboola projenize giriş yaptığınızda tarayıcınızdaki URL'ye bakarak bölgenizi belirleyebilirsiniz:

Bölge	API URL
AWS Kuzey Amerika	https://connection.keboola.com
AWS Avrupa	https://connection.eu-central-1.keboola.com
Google Cloud AB	https://connection.europe-west3.gcp.keboola.com
Google Cloud ABD	https://connection.us-east4.gcp.keboola.com
Azure AB	https://connection.north-europe.azure.keboola.com

KBC_BRANCH_ID (İsteğe Bağlı)

Belirli bir Keboola geliştirme dalında işlem yapmak için, KBC_BRANCH_ID parametresini kullanarak dal kimliğini ayarlayın. MCP sunucusu işlevselliğini belirtilen dalla sınırlar ve tüm değişikliklerin izole kalmasını ve üretim dalını etkilememesini sağlar.

• Sağlanmazsa, sunucu varsayılan olarak üretim dalını kullanır.
• Geliştirme çalışmaları için, KBC_BRANCH_ID değerini dalınızın sayısal kimliğine ayarlayın (ör. 123456). Geliştirme dalı kimliğini, kullanıcı arayüzünde geliştirme dalına giderken URL'de bulabilirsiniz, örneğin: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• Uzak taşımalarda, istek başına X-Branch-Id: <branchId> veya KBC_BRANCH_ID: <branchId> HTTP başlığıyla geçersiz kılabilirsiniz.

Kurulum

Şunlara sahip olduğunuzdan emin olun:

• Python 3.10+ kurulu
• Yönetici haklarına sahip bir Keboola projesine erişim
• Tercih ettiğiniz MCP istemcisi (Claude, Cursor, vb.)

Not: uv kurulu olduğundan emin olun. MCP istemcisi, Keboola MCP Sunucusunu otomatik olarak indirmek ve çalıştırmak için bunu kullanacaktır. uv kurulumu:

macOS/Linux:

#if homebrew is not installed on your machine use:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install using Homebrew
brew install uv

Windows:

# Using the installer script
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Or using winget
winget install --id=astral-sh.uv -e

Daha fazla kurulum seçeneği için resmi uv belgelerine bakın.

Keboola MCP Sunucusunu Çalıştırma

İhtiyaçlarınıza bağlı olarak Keboola MCP Sunucusunu kullanmanın dört yolu vardır:

Seçenek A: Entegre Mod (Önerilen)

Bu modda Claude veya Cursor MCP sunucusunu sizin için otomatik olarak başlatır.

1. Bir kez giriş yapın bir terminalde oturumun saklanması için (istemci sunucuyu arka planda başlatır, burada tarayıcı açılamaz):

   uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
   

2. MCP istemcinizi (Claude/Cursor) aşağıdaki ayarlarla yapılandırın — yalnızca KBC_STORAGE_API_URL gereklidir.
3. İstemci, gerektiğinde MCP sunucusunu otomatik olarak başlatacaktır.

Claude Desktop Yapılandırması

1. Claude'a gidin (ekranınızın sol üst köşesi) -> Ayarlar → Geliştirici → Yapılandırmayı Düzenle (claude_desktop_config.json dosyasını görmüyorsanız oluşturun)
2. Aşağıdaki yapılandırmayı ekleyin:
3. Değişikliklerin etkili olması için Claude masaüstünü yeniden başlatın

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Yapılandırma dosyası konumları:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor Yapılandırması

1. Ayarlar → MCP bölümüne gidin
2. "+ Yeni global MCP Sunucusu Ekle" seçeneğine tıklayın
3. Bu ayarlarla yapılandırın:

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Not: MCP sunucuları için kısa ve açıklayıcı adlar kullanın. Tam araç adı sunucu adını içerdiğinden ve ~60 karakterin altında kalması gerektiğinden, daha uzun adlar Cursor'da filtrelenebilir ve Aracıya gösterilmez.

Windows WSL için Cursor Yapılandırması

MCP sunucusunu Cursor AI ile Windows Subsystem for Linux'tan çalıştırırken şu yapılandırmayı kullanın:

{
  "mcpServers": {
    "keboola":{
      "command": "wsl.exe",
      "args": [
          "bash",
          "-c '",
          "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

Seçenek B: Yerel Geliştirme Modu

MCP sunucu kodu üzerinde çalışan geliştiriciler için:

1. Depoyu klonlayın ve yerel bir ortam kurun
2. Claude/Cursor'ı yerel Python yolunuzu kullanacak şekilde yapılandırın:

{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server --transport <transport>"
      ],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Seçenek C: Manuel CLI Modu (Yalnızca Test İçin)

Sunucuyu test veya hata ayıklama için bir terminalde manuel olarak çalıştırabilirsiniz:

# Sign in once (stores a session under ~/.keboola/mcp), then start the server.
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"

uvx keboola_mcp_server --transport streamable-http

Not: Bu mod öncelikle hata ayıklama veya test içindir. Claude veya Cursor ile normal kullanım için sunucuyu manuel olarak çalıştırmanıza gerek yoktur.

Not: Sunucu Streamable HTTP taşımasını kullanacak ve /mcp adresindeki gelen bağlantılar için localhost:8000 üzerinde dinleyecektir. Başka bir yerde dinletmek için --port ve --host parametrelerini kullanabilirsiniz.

Seçenek D: Docker Kullanma

Bir kapsayıcı tarayıcı açamaz, bu nedenle bir belirteçle kimlik doğrulayın (bkz. Tarayıcı olmadan kimlik doğrulama): KBC_STORAGE_TOKEN değerini bir Keboola erişim/kişisel erişim belirtecine ve KBC_PROJECT_ID değerini hedef projeye ayarlayın. (HTTP üzerinden bunun yerine istek başına X-StorageAPI-Token / X-KBC-ProjectId başlıklarını iletebilir ve bunları atlayabilirsiniz.)

docker pull keboola/mcp-server:latest

docker run \
  --name keboola_mcp_server \
  --rm \
  -it \
  -p 127.0.0.1:8000:8000 \
  -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
  -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_TOKEN" \
  -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

Not: Sunucu Streamable HTTP taşımasını kullanacak ve /mcp adresindeki gelen bağlantılar için localhost:8000 üzerinde dinleyecektir. Kapsayıcının bağlantı noktasını başka bir yere eşlemek için -p değerini değiştirebilirsiniz.

Sunucuyu Kendim Başlatmam Gerekir mi?

Senaryo	Manuel Çalıştırma Gerekli mi?	Bu Kurulumu Kullanın
Claude/Cursor kullanma	Hayır	MCP'yi uygulama ayarlarında yapılandırın
MCP'yi yerel olarak geliştirme	Hayır (Claude başlatır)	Yapılandırmayı python yoluna yönlendirin
CLI'yı manuel test etme	Evet	Çalıştırmak için terminali kullanın
Docker kullanma	Evet	Docker kapsayıcısını çalıştırın

MCP Sunucusunu Kullanma

MCP istemciniz (Claude/Cursor) yapılandırılıp çalıştırıldıktan sonra Keboola verilerinizi sorgulamaya başlayabilirsiniz:

Kurulumunuzu Doğrulayın

Her şeyin çalıştığını doğrulamak için basit bir sorguyla başlayabilirsiniz:

What buckets and tables are in my Keboola project?

Yapabileceklerinize Örnekler

Veri Keşfi:

• "Müşteri bilgilerini içeren tablolar hangileri?"
• "Gelire göre ilk 10 müşteriyi bulmak için bir sorgu çalıştır"

Veri Analizi:

• "Satış verilerimi son çeyrek için bölgeye göre analiz et"
• "Müşteri yaşı ile satın alma sıklığı arasındaki korelasyonları bul"

Veri Hatları:

• "Müşteri ve sipariş tablolarını birleştiren bir SQL dönüşümü oluştur"
• "Salesforce bileşenim için veri çıkarma işini başlat"

Uyumluluk

MCP İstemci Desteği

MCP İstemcisi	Destek Durumu	Bağlantı Yöntemi
Claude (Masaüstü ve Web)	✅ destekleniyor	stdio
Cursor	✅ destekleniyor	stdio
Windsurf, Zed, Replit	✅ Destekleniyor	stdio
Codeium, Sourcegraph	✅ Destekleniyor	Streamable HTTP
Özel MCP İstemcileri	✅ Destekleniyor	Streamable HTTP veya stdio

Desteklenen Araçlar

Not: Yapay zeka aracılarınız yeni araçlara otomatik olarak uyum sağlayacaktır.

Ayrıntılı açıklamalar, parametreler ve kullanım örnekleri içeren mevcut araçların tam listesi için TOOLS.md dosyasına bakın.

Sorun Giderme

Yaygın Sorunlar

Sorun	Çözüm
Kimlik Doğrulama Hataları	keboola_mcp_server login komutunu yeniden çalıştırın (veya bir belirteçle kimlik doğruluyorsanız, belirteci ve KBC_PROJECT_ID değerini doğrulayın)
Bağlantı Zaman Aşımı	Ağ bağlantısını kontrol edin

Geliştirme

Kurulum

Temel kurulum:

uv sync --extra dev

Temel kurulumla, testleri çalıştırmak ve kod stilini kontrol etmek için uv run tox kullanabilirsiniz.

Önerilen kurulum:

uv sync --extra dev --extra tests --extra integtests --extra codestyle

Önerilen kurulumla, test ve kod stili kontrolü için paketler kurulur; bu, VsCode veya Cursor gibi IDE'lerin geliştirme sırasında kodu kontrol etmesine veya testleri çalıştırmasına olanak tanır.

Entegrasyon testleri

Entegrasyon testlerini yerel olarak çalıştırmak için uv run tox -e integtests kullanın. NOT: Aşağıdaki ortam değişkenlerini ayarlamanız gerekecektir:

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Bu değerleri almak için entegrasyon testleri için özel Keboola projelerine ihtiyacınız vardır. Her test oturumu kendi salt okunur çalışma alanını oluşturur, bu nedenle çalışma alanı şeması yapılandırılması gerekmez. Ayrıntılı kurulum talimatları ve tasarım belgeleri için integtests/README.md bölümüne bakın.

uv.lock Güncelleme

Bağımlılık eklediyseniz veya kaldırdıysanız uv.lock dosyasını güncelleyin. Ayrıca, bir sürüm oluştururken daha yeni bağımlılık sürümleriyle kilidi güncellemeyi düşünün (uv lock --upgrade).

Araç Belgelerini Güncelleme

Herhangi bir araç açıklamasında (araç işlevlerindeki docstring'ler) değişiklik yaptığınızda, bu değişiklikleri yansıtmak için TOOLS.md belge dosyasını yeniden oluşturmalısınız:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Sürüm Yayınlama

Birleştirilen her PR için sürüm yayınlamıyoruz. Çalışmalar sürekli olarak ana dala (main) aktarılır ve değişiklikler birlikte yeniden test edildikten sonra periyodik olarak sürüm yayınlarız — bu, kullanıcılar için çalışan kurulumların bozulmasını önler.

Bir sürüm, bir veya iki git etiketi gönderilerek yapılır:

• vX.Y.Z — MCP sunucu sürümü (her zaman)
• agent-vX.Y.Z — In Platform Agent sürümü (yalnızca aracı da yayınlandığında)

Her iki etiket de Docker görüntüsünü oluşturan ve yayınlayan release.yml CI'sini tetikler. KaiBench yalnızca üretim vX.Y.Z etiketlerinde çalışır (agent-vX.Y.Z değil ve -dev. ön sürümleri değil). release-notes becerisini kullanın — sürüm notlarını ve taslak PR'yi hazırlar ve hem vX.Y.Z hem de agent-vX.Y.Z etiketleme sürecinde size yol gösterir.

Destek ve Geri Bildirim

⭐ Yardım almanın, hata bildirmenin veya özellik talep etmenin birincil yolu GitHub'da bir sorun açmaktır. ⭐

Geliştirme ekibi sorunları aktif olarak izler ve mümkün olan en kısa sürede yanıt verir. Keboola hakkında genel bilgi için lütfen aşağıdaki kaynakları kullanın.

Kaynaklar

• Kullanıcı Belgeleri
• Geliştirici Belgeleri
• Keboola Platformu
• Sorun Takipçisi ← MCP Sunucusu için birincil iletişim yöntemi

Bağlantı

• LinkedIn
• Twitter
• Değişiklik Günlüğü