Keboola MCP Server

AI ajanlarınızı, MCP istemcilerinizi (Cursor, Claude, Windsurf, VS Code ...) ve diğer AI asistanlarınızı Keboola'ya bağlayın. Veri, dönüşümler, SQL sorguları ve iş tetikleyicilerini ortaya çıkarın—glue kod gerekmez. Ajanların ihtiyaç duyduğu doğru verileri doğru zamanda ve yerde sunun.

Genel Bakış

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

Hızlı Başlangıç
Yerel Kurulum

Özellikler

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

Depolama: Tabloları doğrudan sorgulayın ve tablo veya demet açıklamalarını yönetin
Bileşenler: Çıkarıcılar, yazıcılar, veri uygulamaları ve dönüşüm yapılandırmaları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 Orchestrator Akışları kullanarak iş akışı boru hatlarını oluşturun ve yönetin
Veri Uygulamaları: Depolama verileriniz üzerinde sorgularınızı görüntüleyen Keboola Streamlit Veri Uygulamalarını oluşturun, dağıtın ve yönetin
Meta veri: Proje belgelerini ve nesne meta verilerini doğal dil kullanarak arayın, okuyun ve güncelleyin
Geliştirme Şubeleri: Prodüksiyonun dışında geliştirme şubelerinde güvenle çalışın; tüm işlemler seçilen şubeye kapsamlıdır

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

Keboola MCP Server'ı kullanmanın en kolay yolu Uzak MCP Sunucusu aracılığıyladır. Bu barındırılan çözüm, yerel kurulum, yapılandırma veya yükleme ihtiyacını ortadan kaldırır.

Uzak MCP Sunucusu Nedir?

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

Nasıl Bağlanılır

Uzak sunucu URL'nizi alın: Keboola Proje Ayarlarına gidin → MCP Server sekmesi
Sunucu URL'sini kopyalayın: https://mcp.<YOUR_REGION>.keboola.com/mcp gibi görünecektir
AI asistanınızı yapılandırın: URL'yi AI asistanınızın MCP ayarlarına yapıştırın
Kimlik doğrulaması yapın: Keboola hesabınız ile kimlik doğrulaması yapmanız ve projenizi seçmeniz istenecektir

Desteklenen İstemciler

Cursor: Projenizin MCP Server ayarlarında "Cursor'a Yükle" düğmesini kullanın veya buraya tıklayın
Claude Desktop: Ayarlar → İntegrasyonlar aracılığıyla entegrasyonu ekleyin
Claude Code: claude mcp add --transport http keboola <URL> kullanarak yükleyin (ayrıntılar için aşağıya bakın)
Windsurf: Uzak sunucu URL'si ile yapılandırın
Make: Uzak sunucu URL'si ile yapılandırın
Diğer MCP istemcileri: Uzak sunucu URL'si ile yapılandırın

Claude Code Kurulumu

Claude Code, terminalinizi kullanarak Claude ile etkileşime girmek için izin veren bir komut satırı arayüzü aracıdır. Basit bir komut kullanarak Keboola MCP Server entegrasyonunu yükleyebilirsiniz.

Yükleme:

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

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

Bölgeye özel komutlar:

Bölge	Yükleme 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:

Yüklendikten sonra, Claude Code'da konuşmanızda /mcp yazıp kullanmak istediğiniz Keboola araçlarını seçerek Keboola MCP Server'ı kullanabilirsiniz.

Kimlik Doğrulaması:

Claude Code'da Keboola MCP Server'ı ilk kez kullandığınızda, bir tarayıcı penceresi açılacak ve sizden aşağıdakileri yapmanız istenecektir:

Keboola hesabınız ile oturum açın
Bağlanmak istediğiniz projeyi seçin
Bağlantıyı yetkilendirin

Kimlik doğrulamasından sonra, Claude Code'dan doğrudan Keboola araçlarını kullanmaya başlayabilirsiniz.

Ayrıntılı kurulum talimatları ve bölgeye özel URL'ler için Uzak Sunucu Kurulum belgelerine bakın.

Geliştirme Şubelerini Kullanma

Prodüksiyondaki verileri etkilemeden Keboola geliştirme şubelerinde güvenle çalışabilirsiniz. Uzaktan barındırılan MCP Sunucuları KBC_BRANCH_ID parametresini saygı gösterir ve tüm işlemleri belirtilen şubeye kapsamlar. Geliştirme şube kimliğini, kullanıcı arayüzünde geliştirme şubesine gittiğinizde URL'de bulabilirsiniz, örneğin: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. Şube kimliği, X-Branch-Id: <branchId> başlığı kullanılarak her istekten eklenmeli, aksi takdirde MCP Server varsayılan olarak prodüksiyonsal şubeyi kullanır. Bunu, AI istemcisi veya sunucu bağlantısını işleyen ortam tarafından yönetilmelidir.

Araç Yetkilendirmesi ve Erişim Kontrolü

HTTP tabanlı aktarımlar (Akışlı HTTP) kullanırken, HTTP başlıklarını kullanarak istemciler için hangi araçların kullanılabileceğini kontrol edebilirsiniz. Bu, AI ajanı yeteneklerini kısıtlamak veya uyumluluk ilkelerini uygulamak için kullanışlıdır.

Yetkilendirme Başlıkları

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

Filtre Davranışı

Filtreler sırasına göre uygulanır: izin verilen → salt okunur kesişim → yasak hariç tutma. Boş başlıklar = kısıtlama yok.

Salt Okunur Araçlar

Salt okunur araçlar, readOnlyHint=True ile açıklanmış olanlardır. Bu araçlar yalnızca Keboola projenizde herhangi bir değişiklik yapmadan bilgi alır. Güncel salt okunur araçlar listesi için, gerçek araç setinin otomatik olarak oluşturulan 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ı belgeler için developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control adresine bakın.

Yerel MCP Sunucusu Kurulumu (Özel veya Geliştirme 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. Depoyu klonlayacak, sunucu aktarımına bağlı olarak Keboola kimlik bilgilerini ortam değişkenleri veya başlıklar aracılığıyla ayarlayacak, bağımlılıkları yükleyecek ve sunucuyu başlatacaksınız. Bu yaklaşım maksimum esneklik (özel araçlar, yerel günlüğe kaydetme, çevrimdışı yineleme) sunar, ancak manuel kurulum gerektirir ve güncellemeleri ile sırları siz yönetirsiniz.

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

stdio - --transport belirtilmediğinde varsayılan. Standart giriş/çıkış, tipik olarak tek bir istemci ile yerel dağıtım için kullanılır.
streamable-http - Sunucuyu çift yönlü akış kanalı ile HTTP üzerinden uzaktan çalıştırır, istemci ve sunucunun sürekli olarak mesaj alışverişi yapmasına izin verir. /mcp aracılığıyla bağlanın (örn. http://localhost:8000/mcp).
http-compat - streamable-http için bir takma ad, geriye dönük uyumluluk için tutulur.

İstemci–sunucu iletişimi için, Keboola kimlik bilgileri, Keboola Bölgenizde projeniz ile çalışmayı etkinleştirmek için sağlanmalıdır. Aşağıdakiler gereklidir: KBC_STORAGE_TOKEN, KBC_STORAGE_API_URL, KBC_WORKSPACE_SCHEMA ve isteğe bağlı olarak KBC_BRANCH_ID. Bunu iki şekilde sağlayabilirsiniz:

Kişisel kullanım için (esas olarak stdio aktarımı ile): sunucuyu başlatmadan önce ortam değişkenlerini ayarlayın. Tüm istekler bu önceden tanımlanmış kimlik bilgilerini yeniden kullanacaktır.
Çok kullanıcılı kullanım için: değişkenleri istek başlıklarına ekleyin, böylece her istek, kendisiyle sağlanan kimlik bilgilerini kullanır.

KBC_STORAGE_TOKEN

Bu, Keboola için kimlik doğrulama belirtecinizdir:

Depolama API belirteçlerini oluşturma ve yönetme talimatları için resmi Keboola belgelerine bakın.

Not: MCP sunucusunun sınırlı erişime sahip olmasını istiyorsanız, özel depolama belirteci kullanın; MCP'nin projenizde her şeye erişmesini istiyorsanız, ana belirteci kullanın.

KBC_WORKSPACE_SCHEMA

Bu, Keboola'da çalışma alanınızı tanımlar ve SQL sorguları için kullanılır. Ancak, bu yalnızca Ana Belirteç yerine özel bir depolama belirteci kullanıyorsanız gereklidir:

Ana Belirteci kullanıyorsanız: Çalışma alanı arka planda otomatik olarak oluşturulur
Özel depolama belirteci kullanıyorsanız: KBC_WORKSPACE_SCHEMA'nız almak için bu Keboola rehberini izleyin

Not: Çalışma alanını el ile oluştururken, Tüm Proje verilerine salt okunur erişim ver seçeneğini işaretleyin

Not: KBC_WORKSPACE_SCHEMA, BigQuery çalışma alanlarında Dataset Name olarak adlandırılır; Bağlan'a tıklayın ve Dataset Name'i kopyalayın

KBC_STORAGE_API_URL (Keboola Bölgesi)

Keboola Bölgesi API URL'niz dağıtım bölgenize bağlıdır. Keboola projenizde oturum açtığınızda tarayıcıdaki 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 şubesinde işlem yapmak için, KBC_BRANCH_ID parametresini kullanarak şube kimliğini ayarlayın. MCP sunucusu, işlevselliğini belirtilen şubeye kapsamlar, tüm değişikliklerin yalıtılmış kalmasını ve prodüksiyonsal şubeyi etkilememesini sağlar.

Sağlanmazsa, sunucu varsayılan olarak prodüksiyonsal şubeyi kullanır.
Geliştirme işi için, KBC_BRANCH_ID'yi şubenizin sayısal kimliğine ayarlayın (örn. 123456). Geliştirme şube kimliğini, kullanıcı arayüzünde geliştirme şubesine gittiğinizde URL'de bulabilirsiniz, örneğin: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
Uzak aktarımlarda, her istek ile X-Branch-Id: <branchId> veya KBC_BRANCH_ID: <branchId> HTTP başlığı ile geçersiz kılabilirsiniz.

Yükleme

Emin olun ki:

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

Not: uv yüklü olduğundan emin olun. MCP istemcisi bunu, Keboola MCP Server'ı otomatik olarak indirmek ve çalıştırmak için kullanacaktır. uv Yükleme:

macOS/Linux:

#eğer homebrew makinenizde yüklü değilse kullanın:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Homebrew kullanarak yükleyin
brew install uv

Windows:

# Yükleyici komut dosyasını kullanarak
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Veya pip kullanarak
pip install uv

# Veya winget kullanarak
winget install --id=astral-sh.uv -e

Daha fazla yükleme seçeneği için resmi uv belgelerine bakın.

Keboola MCP Server'ı Çalıştırma

İhtiyaçlarınıza bağlı olarak Keboola MCP Server'ı 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. Terminalinizde hiçbir komut çalıştırmanız gerekmez.

MCP istemcinizi (Claude/Cursor) uygun ayarlarla yapılandırın
İstemci, gerektiğinde MCP sunucusunu otomatik olarak başlatacaktır

Claude Desktop Yapılandırması

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)
Aşağıdaki yapılandırmayı ekleyin:
Claude masaüstünü değişikliklerin etkili olması için 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_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "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ı

Ayarlar → MCP'ye gidin
"+ Yeni genel MCP Sunucusu Ekle" seçeneğine tıklayın
Şu 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_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Not: MCP sunucuları için kısa, 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 Ajanı tarafından görüntülenmez.

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

MCP sunucusunu Windows Subsystem for Linux'tan Cursor AI ile ç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_STORAGE_TOKEN=your_keboola_storage_token &&",
          "export KBC_WORKSPACE_SCHEMA=your_workspace_schema &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

Seçenek B: Yerel Geliştirme Modu

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

Depoyu klonlayın ve yerel bir ortam kurun
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_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "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 terminalde el ile çalıştırabilirsiniz:

# Ortam değişkenlerini ayarlayın
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
export KBC_STORAGE_TOKEN=your_keboola_storage_token
export KBC_WORKSPACE_SCHEMA=your_workspace_schema
export KBC_BRANCH_ID=your_branch_id_optional

uvx keboola_mcp_server --transport streamable-http

Not: Bu mod, esas olarak hata ayıklama veya test içindir. Claude veya Cursor ile normal kullanım için, sunucuyu el ile çalıştırmanız gerekmez.

Not: Sunucu, Akışlı HTTP aktarımını kullanacak ve /mcp'deki gelen bağlantılar için localhost:8000'i dinleyecektir. İnşa ettiği yeri değiştirmek için --port ve --host parametrelerini kullanabilirsiniz.

Seçenek D: Docker Kullanma

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_STORAGE_TOKEN" \
  -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

Not: Sunucu, Akışlı HTTP aktarımını kullanacak ve /mcp'deki gelen bağlantılar için localhost:8000'i dinleyecektir. Konteyner portunu başka bir yere eşlemek için -p değerini değiştirebilirsiniz.

Sunucuyu Kendim Başlatmam Gerekiyor mu?

Senaryo	El ile Çalıştırılması Gerekiyor mu?	Bu Kurulumu Kullanın
Claude/Cursor Kullanma	Hayır	Uygulamada MCP'yi yapılandırın
Yerel MCP Geliştirme	Hayır (Claude başlatır)	Python yoluna işaret edin
CLI'yı El ile Test Etme	Evet	Terminalde çalıştırmak için kullanın
Docker Kullanma	Evet	Docker konteynerini çalıştırın

MCP Server Kullanımı

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

Kurulumunuzu Doğrulayın

Her şeyin çalışıp çalışmadığını doğrulamak için basit bir sorgu ile başlayabilirsiniz:

Keboola projemde hangi kavanozlar ve tablolar var?

Yapabileceğiniz Şeylere Örnekler

Veri İnceleme:

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

Veri Analizi:

"Son çeyrek için bölgeye göre satış verilerini analiz edin"
"Müşteri yaşı ve satın alma sıklığı arasındaki korelasyonları bulun"

Veri Boru Hatları:

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

Uyumluluk

MCP İstemci Desteği

| **M

keboola/mcp-server

Bu MCP sunucusu hakkında