Keboola

Keboola MCP Server

Hubungkan agen AI, klien MCP (Cursor, Claude, Windsurf, VS Code ...) dan asisten AI lainnya ke Keboola. Sediakan data, transformasi, kueri SQL, dan pemicu job—tanpa perlu kode penghubung. Kirimkan data yang tepat kepada agen, di tempat dan waktu mereka membutuhkannya.

Ringkasan

Keboola MCP Server adalah jembatan sumber terbuka antara proyek Keboola Anda dan alat AI modern. Server ini mengubah fitur Keboola—seperti akses penyimpanan, transformasi SQL, dan pemicu job—menjadi alat yang dapat dipanggil oleh Claude, Cursor, CrewAI, LangChain, Amazon Q, dan lainnya.

• Mulai Cepat
• Penyiapan Lokal

Fitur

Dengan AI Agent dan MCP Server, Anda dapat:

• Penyimpanan: Kueri tabel secara langsung dan kelola deskripsi tabel atau bucket
• Komponen: Buat, tampilkan, dan periksa konfigurasi extractor, writer, aplikasi data, dan transformasi
• SQL: Buat transformasi SQL menggunakan bahasa alami
• Job: Jalankan komponen dan transformasi, serta ambil detail eksekusi job
• Flows: Buat dan kelola pipeline alur kerja menggunakan Conditional Flows dan Orchestrator Flows.
• Aplikasi Data: Buat, deploy, dan kelola Keboola Data Apps yang menampilkan kueri Anda atas data penyimpanan — aplikasi python-js di repositori yang dikelola Keboola atau di repositori GitHub pelanggan (diklon melalui koneksi GitHub organisasi, tanpa kredensial tersimpan), serta aplikasi Streamlit.
• Metadata: Cari, baca, dan perbarui dokumentasi proyek serta metadata objek menggunakan bahasa alami
• Cabang Dev: Bekerja dengan aman di cabang pengembangan di luar produksi, dengan semua operasi dibatasi pada cabang yang dipilih.

---

🚀 Mulai Cepat: Remote MCP Server (Cara Termudah)

Cara termudah menggunakan Keboola MCP Server adalah melalui Remote MCP Server kami. Solusi yang di-host ini menghilangkan kebutuhan akan penyiapan, konfigurasi, atau instalasi lokal.

Apa itu Remote MCP Server?

Server jarak jauh kami di-host di setiap stack Keboola multi-tenant dan mendukung autentikasi OAuth. Anda dapat terhubung ke server ini dari asisten AI mana pun yang mendukung koneksi Streamable HTTP jarak jauh dan autentikasi OAuth.

Cara Menghubungkan

1. Dapatkan URL server jarak jauh Anda: Buka Pengaturan Proyek Keboola → tab MCP Server
2. Salin URL server: Formatnya akan terlihat seperti https://mcp.<YOUR_REGION>.keboola.com/mcp
3. Konfigurasikan asisten AI Anda: Tempelkan URL ke pengaturan MCP asisten AI Anda
4. Autentikasi: Anda akan diminta masuk dengan akun Keboola. Proyek yang akan digunakan dipilih setelahnya, dalam percakapan (misalnya, "daftar proyek Keboola saya" / "gunakan proyek X")

Klien yang Didukung

• Cursor: Gunakan tombol "Install In Cursor" di pengaturan MCP Server proyek Anda atau klik tombol ini
• Claude Desktop: Tambahkan integrasi melalui Pengaturan → Integrasi
• Claude Code: Instal menggunakan claude mcp add --transport http keboola <URL> (lihat detail di bawah)
• Windsurf: Konfigurasikan dengan URL server jarak jauh
• Make: Konfigurasikan dengan URL server jarak jauh
• Klien MCP lainnya: Konfigurasikan dengan URL server jarak jauh

Penyiapan Claude Code

Claude Code adalah alat antarmuka baris perintah yang memungkinkan Anda berinteraksi dengan Claude melalui terminal. Anda dapat menginstal integrasi Keboola MCP Server menggunakan perintah sederhana.

Instalasi:

Jalankan perintah berikut di terminal Anda, ganti <YOUR_REGION> dengan region Keboola Anda:

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

Perintah khusus region:

Region	Perintah Instalasi
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

Penggunaan:

Setelah terinstal, Anda dapat menggunakan Keboola MCP Server di Claude Code dengan mengetik /mcp dalam percakapan dan memilih alat Keboola yang ingin digunakan.

Autentikasi:

Saat pertama kali menggunakan Keboola MCP Server di Claude Code, jendela browser akan terbuka dan meminta Anda untuk:

1. Masuk dengan akun Keboola Anda
2. Mengotorisasi koneksi

Setelah autentikasi, Anda dapat mulai menggunakan alat Keboola langsung dari Claude Code. Pemilihan proyek dilakukan setelahnya, dalam percakapan — cukup tanyakan kepada Claude proyek Keboola mana yang akan digunakan.

Untuk petunjuk penyiapan terperinci dan URL khusus region, lihat dokumentasi Penyiapan Remote Server.

Menggunakan Cabang Pengembangan

Anda dapat bekerja dengan aman di cabang pengembangan Keboola tanpa memengaruhi data produksi. MCP Server yang di-host dari jarak jauh mengikuti parameter KBC_BRANCH_ID dan membatasi semua operasi pada cabang yang ditentukan. Anda dapat menemukan ID cabang pengembangan di URL saat membuka cabang pengembangan di UI, misalnya: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. ID cabang harus disertakan dalam setiap permintaan menggunakan header X-Branch-Id: <branchId>; jika tidak, MCP Server akan menggunakan cabang produksi sebagai default. Hal ini harus dikelola oleh klien AI atau lingkungan yang menangani koneksi server.

Otorisasi Alat dan Kontrol Akses

Saat menggunakan transport berbasis HTTP (Streamable HTTP), Anda dapat mengontrol alat yang tersedia bagi klien menggunakan header HTTP. Ini berguna untuk membatasi kemampuan agen AI atau menerapkan kebijakan kepatuhan.

Header Otorisasi

Header	Deskripsi	Contoh
X-Allowed-Tools	Daftar alat yang diizinkan, dipisahkan dengan koma	get_configs,get_buckets,query_data
X-Disallowed-Tools	Daftar alat yang dikecualikan, dipisahkan dengan koma	create_config,run_job
X-Read-Only-Mode	Batasi hanya untuk alat baca-saja	true, 1, atau yes

Perilaku Filter

Filter diterapkan secara berurutan: diizinkan → irisan baca-saja → pengecualian yang tidak diizinkan. Header kosong = tanpa pembatasan.

Alat Baca-Saja

Alat baca-saja adalah alat yang diberi anotasi readOnlyHint=True. Alat ini hanya mengambil informasi tanpa membuat perubahan apa pun pada proyek Keboola Anda. Untuk daftar alat baca-saja saat ini, lihat file TOOLS.md, yang merupakan snapshot yang dibuat secara otomatis dari kumpulan alat sebenarnya.

Contoh: Akses Baca-Saja

X-Read-Only-Mode: true

Pemuatan Alat Tertunda

Header	Deskripsi	Contoh
X-Deferred-Tools	Daftar alat yang akan ditampilkan dengan _meta["anthropic/alwaysLoad"] = false	run_sync_action,get_flow_schema

Klien Claude Code / Claude Agent SDK yang mendaftarkan server dengan alwaysLoad: true akan mempertahankan alat-alat ini dalam status tertunda di balik pencarian alat, alih-alih memuat definisinya sejak awal. Header ini hanya mengubah metadata tools/list — header ini tidak menyembunyikan atau mengotorisasi alat. Header kosong atau nama alat yang tidak dikenal = tidak ada perubahan.

Untuk dokumentasi terperinci, lihat developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.

Keamanan Tingkat Baris dan Tingkat Kolom

Kebijakan tingkat baris dan tingkat kolom adalah objek Metastore Keboola (rls-policy, cls-policy), yang ditulis melalui API Metastore (perintah kbagent rls / kbagent cls belum tersedia dalam rilis kbagent mana pun). Server ini tidak membaca maupun menerapkannya. Di proyek yang memiliki fitur row-level-security, server membuat workspace-nya (konfigurasi mcp-workspace-<hex> dari komponen keboola.mcp-server-tool) dengan jenis login Connection governed. Workspace yang diatur tidak memiliki kredensial: hanya Query Service yang dapat membacanya, dan Query Service memfilter setiap hasil query_data berdasarkan kebijakan proyek. Server ini tidak melakukan penulisan ulang dan tidak memiliki fallback: apa pun yang ditolak oleh Query Service, query_data akan mengembalikannya sebagai error.

• Yang mengaktifkannya. Fitur proyek hanya diperiksa oleh server ini; Connection tidak memerlukan fitur atau peran untuk membuat workspace yang diatur (Snowflake atau BigQuery, tanpa kunci publik). Connection stack harus menerima jenis login governed untuk backend proyek: stack yang tidak menerimanya akan menolak pembuatan, lalu setiap alat yang memerlukan workspace akan gagal (tidak ada fallback ke workspace biasa). Penegakan di BigQuery belum diverifikasi secara menyeluruh pada stack produksi. Workspace MCP biasa yang lebih lama tidak dihapus: workspace tersebut dilewati begitu fitur diaktifkan. Saat fitur aktif, pin workspace_schema atau X-Workspace-Id hanya diterima untuk workspace yang diatur (workspace biasa akan membaca tanpa mengikuti kebijakan), sehingga pin ke workspace lama, atau ke workspace biasa milik aplikasi data, ditolak; hapus workspace lama.
• Tolak secara default. Tabel yang tidak tercakup oleh rls-policy maupun cls-policy ditolak untuk administrator (agen melihat Row-level security does not allow this query) dan dibaca sebagai tanpa baris untuk pembaca biasa seperti pengguna akhir aplikasi data (aturan "*" membuka tabel bagi setiap pembaca yang teridentifikasi). cls-policy saja membuka tabelnya: semua baris, hanya kolom yang ditentukan, bagi pembaca yang disebutkan; pembaca lain ditolak. Pernyataan yang tidak membaca tabel (SELECT 1) tetap dijalankan.
• Pernyataan yang ditolak. Pernyataan yang diatur ditolak (403, teks umum yang sama untuk setiap alasan) jika menggunakan IDENTIFIER(), TABLE() di luar FROM, fungsi AI (AI_*, BigQuery AI.*), TO_FILE, READ_CSV / READ_PARQUET, SECRET, fungsi konteks sesi (CURRENT_USER, CURRENT_ROLE, CURRENT_STATEMENT, ...), NEXTVAL, $x atau @@x, karakter kontrol, atau nama tanpa tanda kutip yang berisi karakter non-ASCII atau $$, atau jika ukurannya melebihi 32 KiB, 200 CTE, atau 300 referensi tabel. CURRENT_DATE, CURRENT_TIME dan CURRENT_TIMESTAMP tetap diizinkan (per Query Service 1.25 dan policy engine 0.1.8). 503 Row-level security could not be applied to this workspace berarti tidak ada yang dijalankan karena kebijakan tidak dapat diterapkan; kondisi ini mungkin sementara. Pernyataan yang diatur dan gagal mengembalikan The statement failed. Its error text is not shown for a workspace with row-level security.
• Siapa pembacanya. Query Service menentukan pembaca dari token milik administrator sendiri di proyek: token programatik yang diteruskan server ini (kbc_at_ / kbc_pat_, termasuk PAT turunan dari cakupan multi-proyek, dikirim dengan X-KBC-ProjectId) atau token Storage master milik administrator sendiri. Token lainnya (integrasi, aplikasi data, Kai) tidak mengidentifikasi pengguna akhir, tidak memiliki identitas terverifikasi, dan tidak dapat membaca apa pun dari tabel yang diatur. Subjek administrator adalah keboola|<adminId> dan identitas tersebut tidak membawa grup, sehingga aturan grup tidak pernah cocok.
• Binding. Tanpa binding, workspace mendapatkan semua kebijakan proyek, dan server ini tidak pernah membuat binding. Untuk memberikan workspace hanya sebagian kebijakan, ikat kebijakan tersebut ke KID-nya: KID:<stack-id>:project-<project-id>:workspace-<workspace-id> (workspace dari cabang default; workspace cabang juga memiliki branch-<branch-id> sebelum project). ID stack adalah ID yang dikonfigurasi pada Query Service (QUERY_RLS_STACK_ID, misalnya dev-keboola-aws-eu-west-1), ID workspace ada di keluaran get_project_info, dan objek Metastore policy-binding dengan KID tersebut menulis binding (perintah kbagent untuk ini belum dirilis). Binding adalah daftar izin: binding hanya mempertahankan kebijakan yang tercantum, sehingga kebijakan apa pun dapat dikecualikan, termasuk kebijakan cakupan organisasi, dan akses dapat dilonggarkan. Binding yang tidak mencantumkan rls-policy akan menghapus semua kebijakan baris, sehingga tabel yang tercakup oleh cls-policy yang dipertahankan akan terbuka dengan semua baris. Binding berlaku untuk kueri berikutnya dan tidak mengikuti sesi ke workspace lain: sesi cabang, atau workspace yang dibuat ulang, memiliki KID baru dan kembali menggunakan semua kebijakan.
• Batasan. ID workspace server juga merupakan nilai yang diterima aplikasi data sebagai WORKSPACE_ID jika tidak ada workspace terpisah yang disediakan untuknya; aplikasi tersebut membuat kueri dengan tokennya sendiri, tidak memiliki identitas terverifikasi, dan tidak dapat membaca apa pun dari tabel yang diatur.
• Metadata. Alat metadata hanya menampilkan hal-hal yang diizinkan Query Service untuk dibaca oleh pembaca. get_tables dan search (yang kemudian tidak menggunakan pencarian global karena jumlahnya mencakup tabel tersembunyi) tidak menyertakan tabel yang tidak boleh dibaca oleh pembaca, dan get_tables melaporkan tabel yang diminta berdasarkan ID sebagai tidak ditemukan; tabel dengan kebijakan kolom hanya menampilkan kolom yang diizinkan oleh kebijakan tersebut (juga pada kunci utamanya dan dalam hasil pencocokan search). Tabel yang dapat dibaca ditampilkan tanpa jumlah baris dan ukurannya, karena keduanya menghitung baris yang disembunyikan oleh kebijakan baris. get_buckets tetap mencantumkan setiap bucket, tetapi tanpa jumlah tabel dan ukurannya, karena keduanya menghitung tabel tersembunyi. Fitur ini memerlukan endpoint Query Service POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope, dan gagal secara tertutup: jika Query Service tidak dapat memastikan, alat pada proyek yang diatur akan mengembalikan kesalahan dengan pesan singkat dan tanpa tabel. Proyek tanpa fitur ini tidak terpengaruh dan tidak melakukan panggilan tambahan.

---

Penyiapan MCP Server Lokal (Cara Kustom atau Dev)

Jalankan MCP server di komputer Anda sendiri untuk mendapatkan kendali penuh dan kemudahan pengembangan. Pilih cara ini jika Anda ingin menyesuaikan alat, melakukan debug secara lokal, atau melakukan iterasi dengan cepat. Anda akan menginstal server, melakukan autentikasi (login browser satu kali — tanpa token untuk ditempel), lalu menjalankannya. Cara ini menawarkan fleksibilitas maksimum (alat kustom, pencatatan lokal, iterasi offline), tetapi memerlukan penyiapan manual dan Anda mengelola pembaruan serta rahasia sendiri.

Server mendukung beberapa opsi transport, yang dapat dipilih dengan memberikan argumen --transport <transport> saat memulai server:

• stdio - Default jika --transport tidak ditentukan. Input/output standar, biasanya digunakan untuk penerapan lokal dengan satu klien.
• streamable-http - Menjalankan server dari jarak jauh melalui HTTP dengan kanal streaming dua arah, sehingga klien dan server dapat terus bertukar pesan. Hubungkan melalui /mcp (misalnya, http://localhost:8000/mcp).
• http-compat - Alias untuk streamable-http, dipertahankan demi kompatibilitas ke belakang.

Untuk bekerja dengan proyek Keboola Anda, server memerlukan dua hal: Region Keboola Anda (KBC_STORAGE_API_URL) dan cara untuk melakukan autentikasi. Cara yang disarankan adalah login browser satu kali — Anda tidak perlu membuat, menyalin, atau menempelkan token. Secara opsional, atur KBC_BRANCH_ID untuk bekerja di dalam cabang pengembangan.

Beberapa variabel tidak diambil dari header permintaan:

• KBC_STORAGE_API_URL: server yang dimulai dengan URL Storage API sendiri (parameter --api-url atau variabel lingkungan KBC_STORAGE_API_URL) hanya melayani satu stack Keboola tersebut. Header X-Storage-Api-Url yang meminta host lain akan diabaikan (peringatan dicatat) — server tetap menggunakan URL miliknya untuk permintaan tersebut. Mulai server tanpa URL Storage API sendiri jika Anda ingin setiap permintaan dapat memilih stack.
• KBC_KUBERNETES_TOKEN_PATH (hanya server yang diterapkan, lihat docs/kubernetes-sa-auth.md): hanya dibaca dari lingkungan, tidak pernah dari header.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: prinsipnya sama seperti URL Storage API di atas — server yang dimulai dengan pin workspace sendiri (melalui salah satu variabel, atau --workspace-id) akan mempertahankan pin tersebut untuk setiap permintaan; header X-Workspace-Id atau X-Workspace-Schema yang meminta workspace lain akan diabaikan (peringatan dicatat). Server tanpa pin sendiri (kasus bersama multi-pengguna) akan terus mengambil pin dari permintaan, untuk setiap permintaan, seperti dijelaskan di bawah.

Login

Masuk sekali melalui browser; server menyimpan sesi dan memperbaruinya secara otomatis, sehingga tidak ada token yang perlu dikelola:

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

Tindakan ini membuka browser untuk masuk ke Keboola, lalu menyimpan sesi untuk seluruh stack ke ~/.keboola/mcp/credentials.json (hanya dapat dibaca oleh Anda, satu entri per stack). Setelah itu, mulai server hanya dengan KBC_STORAGE_API_URL yang diatur — tidak perlu token. Proyek yang akan digunakan dipilih kemudian, dalam percakapan (get_accessible_projects / set_project_scope), bukan saat login.

Perintah	Fungsinya
login --api-url <url>	Masuk ke stack
login --force	Masuk lagi / beralih akun
login --show-token	Cetak token sesi saat ini (debugging)
logout [--api-url <url>] [--all]	Hapus sesi tersimpan untuk satu stack (atau semua stack)

Saat Anda memulai server melalui stdio di terminal interaktif tanpa sesi tersimpan, server akan menjalankan login browser ini secara otomatis saat pertama kali dimulai. Klien MCP (Claude, Cursor, …) menjalankan server di latar belakang, tempat browser tidak dapat dibuka, jadi jalankan login sendiri sekali terlebih dahulu.

Memulai tanpa akun Keboola

Anda juga dapat memulai server hanya dengan KBC_STORAGE_API_URL dan tanpa kredensial sama sekali. Server akan berjalan dalam mode bootstrap: alat yang memerlukan akses Keboola akan menjelaskan cara mendapatkan kredensial, dan satu alat dapat digunakan tanpa kredensial — create_project. Alat ini membuat proyek Keboola baru, memasukkan sesi ke dalamnya, dan mengembalikan URL konfirmasi. Membuka URL tersebut di browser dan masuk akan menjadikan proyek itu milik Anda secara permanen; sampai saat itu, proyek bersifat sementara dan Keboola dapat mengambilnya kembali. Setelah Anda mengonfirmasi, sesi yang dibuat oleh alat akan dicabut dan Anda dapat melanjutkan dengan login milik Anda sendiri.

Fitur ini memerlukan stack dengan penyediaan agen yang diaktifkan; jika tidak, alat akan melaporkan bahwa fitur tersebut tidak tersedia.

Hal yang sama dapat dilakukan tanpa menjalankan server sama sekali, pada MCP server yang di-host dari jarak jauh dan operatornya telah mengaktifkan fitur ini (KBC_ALLOW_ANONYMOUS_PROVISIONING): penerapan seperti itu juga menyediakan https://mcp.<stack>/mcp-anonymous, yang tidak menerima kredensial. Arahkan klien Anda ke sana tanpa autentikasi, panggil create_project, lalu lanjutkan bekerja di proyek yang dibuat oleh panggilan tersebut — server menyimpan kredensial untuk Anda dan alat memberikan scope_token buram untuk dikirim ulang pada panggilan berikutnya. URL-nya terpisah karena endpoint /mcp biasa harus tetap menolak permintaan tanpa autentikasi: penolakan itulah yang memberi tahu klien MCP untuk memulai login OAuth. Setelah Anda mengklaim proyek tersebut, beralihlah ke /mcp dan masuk dengan akun yang kini memilikinya.

Autentikasi tanpa browser

Untuk kontainer atau CI yang tidak memungkinkan login browser, berikan token akses atau token akses pribadi Keboola secara langsung — atur KBC_STORAGE_TOKEN (variabel env) atau kirim header X-StorageAPI-Token — bersama KBC_PROJECT_ID (atau header X-KBC-ProjectId) untuk memilih proyek. Pada transport HTTP, nilai-nilai ini dapat diberikan sebagai header per permintaan, sehingga setiap permintaan membawa kredensialnya sendiri.

KBC_WORKSPACE_ID

Mengunci kueri ke satu workspace tertentu yang sudah ada berdasarkan ID-nya, alih-alih menggunakan pencarian berbasis skema di atas, dan diutamakan daripada KBC_WORKSPACE_SCHEMA jika keduanya diatur. Opsi ini digunakan oleh pemanggil Data App / kai-agent, yang memberikan nilai tersebut melalui header X-Workspace-Id, agar Kai yang disematkan di aplikasi itu hanya membuat kueri melalui workspace miliknya sendiri.

Atur melalui variabel lingkungan KBC_WORKSPACE_ID, flag CLI --workspace-id, atau (per permintaan, untuk penerapan multi-pengguna) header X-Workspace-Id.

KBC_STORAGE_API_URL (Region Keboola)

URL API Region Keboola Anda bergantung pada region penerapan. Anda dapat mengetahui region dengan melihat URL di browser saat masuk ke proyek Keboola:

Region	URL API
AWS Amerika Utara	https://connection.keboola.com
AWS Eropa	https://connection.eu-central-1.keboola.com
Google Cloud EU	https://connection.europe-west3.gcp.keboola.com
Google Cloud US	https://connection.us-east4.gcp.keboola.com
Azure EU	https://connection.north-europe.azure.keboola.com

KBC_BRANCH_ID (Opsional)

Untuk beroperasi pada cabang pengembangan Keboola tertentu, atur ID cabang menggunakan parameter KBC_BRANCH_ID. MCP server membatasi fungsinya pada cabang yang ditentukan, sehingga semua perubahan tetap terisolasi dan tidak memengaruhi cabang produksi.

• Jika tidak ditentukan, server menggunakan branch produksi secara default.
• Untuk pekerjaan pengembangan, atur KBC_BRANCH_ID ke ID numerik branch Anda (misalnya, 123456). Anda dapat menemukan ID branch pengembangan di URL saat membuka branch pengembangan di UI, misalnya: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• Pada transport jarak jauh, Anda dapat mengganti nilainya untuk setiap permintaan menggunakan header HTTP X-Branch-Id: <branchId> atau KBC_BRANCH_ID: <branchId>.

Instalasi

Pastikan Anda memiliki:

• Python 3.11+ terinstal
• Akses ke proyek Keboola dengan hak admin
• Klien MCP pilihan Anda (Claude, Cursor, dll.)

Catatan: Pastikan uv telah terinstal. Klien MCP akan menggunakannya untuk mengunduh dan menjalankan Keboola MCP Server secara otomatis. Menginstal uv:

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

Untuk opsi instalasi lainnya, lihat dokumentasi resmi uv.

Menjalankan Keboola MCP Server

Ada empat cara untuk menggunakan Keboola MCP Server, bergantung pada kebutuhan Anda:

Opsi A: Mode Terintegrasi (Direkomendasikan)

Dalam mode ini, Claude atau Cursor akan memulai server MCP secara otomatis untuk Anda.

1. Login sekali di terminal agar sesi tersimpan (klien menjalankan server di latar belakang, tempat browser tidak dapat dibuka):

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

2. Konfigurasikan klien MCP Anda (Claude/Cursor) dengan pengaturan di bawah — hanya KBC_STORAGE_API_URL yang diperlukan.
3. Klien akan menjalankan server MCP secara otomatis saat diperlukan.

Konfigurasi Claude Desktop

1. Buka Claude (pojok kiri atas layar Anda) -> Settings → Developer → Edit Config (jika claude_desktop_config.json tidak terlihat, buat file tersebut)
2. Tambahkan konfigurasi berikut:
3. Mulai ulang Claude desktop agar perubahan diterapkan

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

Lokasi file konfigurasi:

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

Konfigurasi Cursor

1. Buka Settings → MCP
2. Klik "+ Add new global MCP Server"
3. Konfigurasikan dengan pengaturan berikut:

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

Catatan: Gunakan nama server MCP yang singkat dan deskriptif. Karena nama alat lengkap mencakup nama server dan harus kurang dari ~60 karakter, nama yang lebih panjang mungkin difilter di Cursor dan tidak akan ditampilkan kepada Agent.

Konfigurasi Cursor untuk Windows WSL

Saat menjalankan server MCP dari Windows Subsystem for Linux dengan Cursor AI, gunakan konfigurasi ini:

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

Opsi B: Mode Pengembangan Lokal

Untuk pengembang yang mengerjakan kode server MCP itu sendiri:

1. Klon repositori dan siapkan lingkungan lokal
2. Konfigurasikan Claude/Cursor agar menggunakan jalur Python lokal Anda:

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

Opsi C: Mode CLI Manual (Hanya untuk Pengujian)

Anda dapat menjalankan server secara manual di terminal untuk pengujian atau debugging:

# 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

Catatan: Mode ini terutama ditujukan untuk debugging atau pengujian. Untuk penggunaan normal dengan Claude atau Cursor, Anda tidak perlu menjalankan server secara manual.

Catatan: Server akan menggunakan transport Streamable HTTP dan mendengarkan di localhost:8000 untuk koneksi masuk di /mcp. Anda dapat menggunakan parameter --port dan --host agar server mendengarkan di tempat lain.

Opsi D: Menggunakan Docker

Kontainer tidak dapat membuka browser, jadi lakukan autentikasi dengan token (lihat Melakukan autentikasi tanpa browser): atur KBC_STORAGE_TOKEN ke token akses/akses pribadi Keboola dan KBC_PROJECT_ID ke proyek target. (Melalui HTTP, Anda dapat menggunakan header X-StorageAPI-Token / X-KBC-ProjectId untuk setiap permintaan dan tidak perlu mengatur nilai-nilai ini.)

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

Catatan: Server akan menggunakan transport Streamable HTTP dan mendengarkan di localhost:8000 untuk koneksi masuk di /mcp. Anda dapat mengubah -p untuk memetakan port kontainer ke lokasi lain.

Apakah Saya Perlu Memulai Server Sendiri?

Skenario	Perlu Menjalankan Secara Manual?	Gunakan Pengaturan Ini
Menggunakan Claude/Cursor	Tidak	Konfigurasikan MCP di pengaturan aplikasi
Mengembangkan MCP secara lokal	Tidak (Claude yang memulainya)	Arahkan konfigurasi ke jalur python
Menguji CLI secara manual	Ya	Jalankan melalui terminal
Menggunakan Docker	Ya	Jalankan kontainer docker

Menggunakan MCP Server

Setelah klien MCP Anda (Claude/Cursor) dikonfigurasikan dan berjalan, Anda dapat mulai mengajukan kueri ke data Keboola:

Memverifikasi Pengaturan

Anda dapat memulai dengan kueri sederhana untuk memastikan semuanya berfungsi:

What buckets and tables are in my Keboola project?

Contoh Hal yang Dapat Anda Lakukan

Eksplorasi Data:

• "Tabel mana yang berisi informasi pelanggan?"
• "Jalankan kueri untuk menemukan 10 pelanggan teratas berdasarkan pendapatan"

Analisis Data:

• "Analisis data penjualan saya berdasarkan wilayah untuk kuartal terakhir"
• "Temukan korelasi antara usia pelanggan dan frekuensi pembelian"

Pipeline Data:

• "Buat transformasi SQL yang menggabungkan tabel pelanggan dan pesanan"
• "Mulai tugas ekstraksi data untuk komponen Salesforce saya"

Kompatibilitas

Dukungan Klien MCP

Klien MCP	Status Dukungan	Metode Koneksi
Claude (Desktop & Web)	✅ didukung	stdio
Cursor	✅ didukung	stdio
Windsurf, Zed, Replit	✅ Didukung	stdio
Codeium, Sourcegraph	✅ Didukung	Streamable HTTP
Klien MCP Kustom	✅ Didukung	Streamable HTTP atau stdio

Alat yang Didukung

Catatan: Agen AI Anda akan menyesuaikan diri secara otomatis dengan alat baru.

Untuk daftar lengkap alat yang tersedia beserta deskripsi terperinci, parameter, dan contoh penggunaan, lihat TOOLS.md.

Pemecahan Masalah

Masalah Umum

Masalah	Solusi
Kesalahan Autentikasi	Jalankan kembali keboola_mcp_server login (atau, jika melakukan autentikasi dengan token, verifikasi token dan KBC_PROJECT_ID)
Waktu Tunggu Koneksi Habis	Periksa konektivitas jaringan

Pengembangan

Instalasi

Penyiapan dasar:

uv sync --extra dev

Dengan penyiapan dasar, Anda dapat menggunakan uv run tox untuk menjalankan pengujian dan memeriksa gaya kode.

Penyiapan yang direkomendasikan:

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

Dengan penyiapan yang direkomendasikan, paket untuk pengujian dan pemeriksaan gaya kode akan diinstal sehingga IDE seperti VsCode atau Cursor dapat memeriksa kode atau menjalankan pengujian selama pengembangan.

Pengujian integrasi

Untuk menjalankan pengujian integrasi secara lokal, gunakan uv run tox -e integtests. CATATAN: Anda perlu mengatur variabel lingkungan berikut:

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Untuk mendapatkan nilai-nilai ini, Anda memerlukan proyek Keboola khusus untuk pengujian integrasi. Setiap sesi pengujian membuat workspace hanya-baca sendiri, jadi skema workspace tidak perlu dikonfigurasikan. Lihat integtests/README.md untuk petunjuk penyiapan terperinci dan dokumentasi desain.

Memperbarui uv.lock

Perbarui file uv.lock jika Anda menambahkan atau menghapus dependensi. Pertimbangkan juga untuk memperbarui lock dengan versi dependensi yang lebih baru saat membuat rilis (uv lock --upgrade).

Memperbarui Dokumentasi Alat

Saat Anda mengubah deskripsi alat apa pun (docstring dalam fungsi alat), Anda harus membuat ulang file dokumentasi TOOLS.md agar mencerminkan perubahan tersebut:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Rilis

Kami tidak membuat rilis untuk setiap PR yang digabungkan. Perubahan terus-menerus masuk ke trunk (main), dan kami merilis secara berkala setelah perubahan diuji ulang bersama-sama — hal ini mencegah kerusakan pada konfigurasi pengguna yang sudah berfungsi.

Rilis dibuat dengan mendorong satu atau dua tag git:

• vX.Y.Z — rilis MCP server (selalu)
• agent-vX.Y.Z — rilis In Platform Agent (hanya saat agent juga dirilis)

Kedua tag akan memicu CI release.yml, yang membangun dan menerbitkan image Docker. KaiBench hanya berjalan pada tag vX.Y.Z produksi (bukan agent-vX.Y.Z, dan bukan prarilis -dev.). Gunakan skill release-notes — skill ini menyiapkan catatan rilis dan PR draf serta memandu proses pemberian tag pada vX.Y.Z dan agent-vX.Y.Z.

Dukungan dan Masukan

⭐ Cara utama untuk mendapatkan bantuan, melaporkan bug, atau meminta fitur adalah dengan membuka issue di GitHub. ⭐

Tim pengembangan secara aktif memantau issue dan akan merespons secepat mungkin. Untuk informasi umum tentang Keboola, silakan gunakan sumber daya di bawah ini.

Sumber Daya

• Dokumentasi Pengguna
• Dokumentasi Pengembang
• Platform Keboola
• Pelacak Issue ← Metode kontak utama untuk MCP Server

Terhubung

• LinkedIn
• Twitter
• Changelog