Keboola

官方

在一個直觀的平台上建立強大的數據工作流程、整合與分析。

GitHub

你可以用 Keboola MCP 做什麼？

Query storage data — Ask for buckets and tables in your project, or run SQL queries like "top 10 customers by revenue" via query_data.
Create SQL transformations — Describe a transformation in natural language, e.g., joining customer and order tables, and have it created for you.
Run and monitor jobs — Trigger components or transformations with run_job and retrieve execution details.
Manage components — List, create, and inspect extractors, writers, data apps, and transformation configs with get_configs and create_config.
Work in dev branches — Scope all operations to a development branch via KBC_BRANCH_ID or X-Branch-Id to keep production untouched.

文件

Keboola MCP Server

將您的 AI 代理、MCP 用戶端（Cursor、Claude、Windsurf、VS Code 等）以及其他 AI 助理連接到 Keboola。公開資料、轉換、SQL 查詢和作業觸發器——無需黏合程式碼。在代理需要時，將正確的資料傳遞給它們。

概述

Keboola MCP Server 是連接您的 Keboola 專案與現代 AI 工具的開源橋樑。它將 Keboola 的功能——如儲存存取、SQL 轉換和作業觸發器——轉化為可供 Claude、Cursor、CrewAI、LangChain、Amazon Q 等使用的可呼叫工具。

快速入門
本機設定

功能

使用 AI Agent 和 MCP Server，您可以：

儲存：直接查詢表格並管理表格或儲存桶描述
元件：建立、列出和檢查提取器、寫入器、資料應用程式和轉換配置
SQL：使用自然語言建立 SQL 轉換
作業：執行元件和轉換，並檢索作業執行詳細資料
流程：使用條件流程和編排器流程建立和管理工作管線。
資料應用程式：建立、部署和管理 Keboola Streamlit 資料應用程式，顯示您對儲存資料的查詢。
中繼資料：使用自然語言搜尋、讀取和更新專案文件及物件中繼資料
開發分支：在生產環境之外的開發分支中安全工作，所有操作都限定在所選分支內。

🚀 快速入門：遠端 MCP Server（最簡單的方式）

使用 Keboola MCP Server 最簡單的方式是透過我們的遠端 MCP Server。這個託管解決方案無需本機設定、配置或安裝。

什麼是遠端 MCP Server？

我們的遠端伺服器託管在每個多租戶 Keboola 堆疊上，並支援 OAuth 認證。您可以從任何支援遠端 Streamable HTTP 連線和 OAuth 認證的 AI 助理連接到它。

如何連接

取得您的遠端伺服器 URL：前往您的 Keboola 專案設定 → MCP Server 分頁
複製伺服器 URL：它看起來像 https://mcp.<YOUR_REGION>.keboola.com/mcp
配置您的 AI 助理：將 URL 貼到您 AI 助理的 MCP 設定中
認證：系統會提示您使用 Keboola 帳戶進行認證並選擇您的專案

支援的用戶端

Cursor：在您專案的 MCP Server 設定中使用「Install In Cursor」按鈕，或點擊此按鈕
Claude Desktop：透過設定 → 整合新增整合
Claude Code：使用 claude mcp add --transport http keboola <URL> 安裝（詳見下文）
Windsurf：使用遠端伺服器 URL 進行配置
Make：使用遠端伺服器 URL 進行配置
其他 MCP 用戶端：使用遠端伺服器 URL 進行配置

Claude Code 設定

Claude Code 是一個命令列介面工具，讓您可以使用終端機與 Claude 互動。您可以使用簡單的命令安裝 Keboola MCP Server 整合。

安裝：

在您的終端機中執行以下命令，將 <YOUR_REGION> 替換為您的 Keboola 區域：

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

區域特定命令：

區域	安裝命令
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`

使用方式：

安裝後，您可以在 Claude Code 中輸入 /mcp 並選擇要使用的 Keboola 工具，來使用 Keboola MCP Server。

認證：

當您第一次在 Claude Code 中使用 Keboola MCP Server 時，會開啟一個瀏覽器視窗，提示您：

使用您的 Keboola 帳戶登入
選擇要連接的專案
授權連線

認證完成後，您就可以直接從 Claude Code 開始使用 Keboola 工具。

如需詳細的設定說明和區域特定 URL，請參閱我們的遠端伺服器設定文件。

使用開發分支

您可以在 Keboola 開發分支中安全工作，而不影響您的生產資料。遠端託管的 MCP Server 會尊重 KBC_BRANCH_ID 參數，並將所有操作限定在所指定的分支。您可以在 UI 中瀏覽開發分支時於 URL 中找到開發分支 ID，例如：https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard。分支 ID 必須使用標頭 X-Branch-Id: <branchId> 包含在每個請求中，否則 MCP Server 預設使用生產分支。這應由處理伺服器連線的 AI 用戶端或環境來管理。

工具授權與存取控制

使用 HTTP 傳輸（Streamable HTTP）時，您可以使用 HTTP 標頭控制哪些工具可供用戶端使用。這對於限制 AI 代理功能或執行合規政策非常有用。

授權標頭

標頭	描述	範例
`X-Allowed-Tools`	允許的工具清單（逗號分隔）	`get_configs,get_buckets,query_data`
`X-Disallowed-Tools`	要排除的工具清單（逗號分隔）	`create_config,run_job`
`X-Read-Only-Mode`	僅限制為唯讀工具	`true`、`1` 或 `yes`

篩選行為

篩選依序套用：允許 → 唯讀交集 → 排除。空標頭 = 無限制。

唯讀工具

唯讀工具是那些標記為 readOnlyHint=True 的工具。這些工具僅檢索資訊，不會對您的 Keboola 專案進行任何變更。如需目前的唯讀工具清單，請參閱 TOOLS.md 檔案，這是實際工具集的自動產生快照。

範例：唯讀存取

X-Read-Only-Mode: true

如需詳細文件，請參閱 developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control。

本機 MCP Server 設定（自訂或開發方式）

在您自己的機器上執行 MCP server，以獲得完全控制並方便開發。當您想要自訂工具、在本機除錯或快速迭代時，請選擇此方式。您將複製儲存庫、透過環境變數或標頭（取決於伺服器傳輸方式）設定 Keboola 憑證、安裝相依套件，然後啟動伺服器。這種方式提供最大的靈活性（自訂工具、本機日誌、離線迭代），但需要手動設定，且您需自行管理更新和機密。

伺服器支援多種傳輸選項，可透過在啟動伺服器時提供 --transport <transport> 參數來選擇：

stdio - 當未指定 --transport 時的預設值。標準輸入/輸出，通常用於單一用戶端的本機部署。
streamable-http - 透過 HTTP 以雙向串流通道遠端執行伺服器，允許用戶端和伺服器持續交換訊息。透過 /mcp 連接（例如 http://localhost:8000/mcp）。
http-compat - streamable-http 的別名，為向後相容而保留。

對於用戶端-伺服器通訊，必須提供 Keboola 憑證才能讓您在 Keboola 區域中操作專案。需要以下項目：KBC_STORAGE_TOKEN、KBC_STORAGE_API_URL、KBC_WORKSPACE_SCHEMA 以及可選的 KBC_BRANCH_ID。您可以透過兩種方式提供：

個人使用（主要用於 stdio 傳輸）：在啟動伺服器前設定環境變數。所有請求都會重複使用這些預先定義的憑證。
多使用者使用：將變數包含在請求標頭中，以便每個請求使用隨請求提供的憑證。

其中有兩個變數不會從請求標頭取得：

KBC_STORAGE_API_URL：以自身 Storage API URL（--api-url 參數或 KBC_STORAGE_API_URL 環境變數）啟動的伺服器只服務於該 Keboola 堆疊。要求不同主機的 X-Storage-Api-Url 標頭會被忽略（會記錄警告）——伺服器會保留自己的 URL 來處理請求。如果您希望每個請求自行選擇其堆疊，請在沒有自身 Storage API URL 的情況下啟動伺服器。
KBC_KUBERNETES_TOKEN_PATH（僅限已部署的伺服器，請參閱 docs/kubernetes-sa-auth.md）：僅從環境讀取，絕不從標頭讀取。

KBC_STORAGE_TOKEN

這是您的 Keboola 認證令牌：

如需建立和管理 Storage API 令牌的說明，請參閱官方 Keboola 文件。

注意：如果您希望 MCP server 具有受限存取權限，請使用自訂儲存令牌；如果您希望 MCP 存取專案中的所有內容，請使用主令牌。

KBC_WORKSPACE_SCHEMA

這識別您在 Keboola 中的工作區，用於 SQL 查詢。但是，這僅在您使用自訂儲存令牌而非主令牌時才需要：

如果使用主令牌：工作區會在幕後自動建立
如果使用自訂儲存令牌：請依照此 Keboola 指南取得您的 KBC_WORKSPACE_SCHEMA

注意：手動建立工作區時，請勾選「授予對所有專案資料的唯讀存取權限」選項

注意：KBC_WORKSPACE_SCHEMA 在 BigQuery 工作區中稱為資料集名稱，您只需點擊連接並複製資料集名稱

KBC_STORAGE_API_URL（Keboola 區域）

您的 Keboola 區域 API URL 取決於您的部署區域。您可以透過登入 Keboola 專案時瀏覽器中的 URL 來判斷您的區域：

區域	API URL
AWS North America	`https://connection.keboola.com`
AWS Europe	`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（可選）

若要操作特定的 Keboola 開發分支，請使用 KBC_BRANCH_ID 參數設定分支 ID。MCP server 會將其功能限定在所指定的分支，確保所有變更保持隔離且不會影響生產分支。

如果未提供，伺服器預設使用生產分支。
對於開發工作，請將 KBC_BRANCH_ID 設定為您分支的數字 ID（例如 123456）。您可以在 UI 中瀏覽開發分支時於 URL 中找到開發分支 ID，例如：https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard。
在遠端傳輸中，您可以使用 HTTP 標頭 X-Branch-Id: <branchId> 或 KBC_BRANCH_ID: <branchId> 覆寫每個請求的設定。

安裝

請確保您具備：

已安裝 Python 3.10+
擁有 Keboola 專案的管理員權限存取
您偏好的 MCP 用戶端（Claude、Cursor 等）

注意：請確保已安裝 uv。MCP 用戶端將使用它來自動下載並執行 Keboola MCP Server。 安裝 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

如需更多安裝選項，請參閱官方 uv 文件。

執行 Keboola MCP Server

根據您的需求，有四種使用 Keboola MCP Server 的方式：

選項 A：整合模式（建議）

在此模式中，Claude 或 Cursor 會自動為您啟動 MCP server。您無需在終端機中執行任何命令。

使用適當的設定配置您的 MCP 用戶端（Claude/Cursor）
用戶端會在需要時自動啟動 MCP server

Claude Desktop 設定

前往 Claude（螢幕左上角）-> 設定 → 開發人員 → 編輯配置（如果您看不到 claude_desktop_config.json，請建立它）
新增以下配置：
重新啟動 Claude desktop 使變更生效

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

配置文件位置：

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

Cursor 設定

前往「設定」→「MCP」
點擊「+ 新增全域 MCP Server」
使用這些設定進行配置：

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

注意：請為 MCP Server 使用簡短且具描述性的名稱。由於完整的工具名稱包含伺服器名稱且必須保持在約 60 個字元以內，較長的名稱可能會在 Cursor 中被過濾掉，且不會顯示給 Agent。

適用於 Windows WSL 的 Cursor 設定

當您從 Windows Subsystem for Linux 搭配 Cursor AI 執行 MCP Server 時，請使用此設定：

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

選項 B：本機開發模式

適用於正在開發 MCP Server 程式碼本身的開發者：

複製儲存庫並設定本機環境
設定 Claude/Cursor 使用您的本機 Python 路徑：

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

選項 C：手動 CLI 模式（僅供測試）

您可以在終端機中手動執行伺服器以進行測試或除錯：

# Set environment variables
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

注意：此模式主要用於除錯或測試。若要在 Claude 或 Cursor 中正常使用，您不需要手動執行伺服器。

注意：伺服器將使用 Streamable HTTP 傳輸，並監聽 localhost:8000 以接收 /mcp 上的連線。您可以使用 --port 和 --host 參數讓它監聽其他位置。

選項 D：使用 Docker

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

注意：伺服器將使用 Streamable HTTP 傳輸，並監聽 localhost:8000 以接收 /mcp 上的連線。您可以變更 -p 以將容器的連接埠對應到其他位置。

我需要自己啟動伺服器嗎？

情境	需要手動執行？	使用此設定
使用 Claude/Cursor	否	在應用程式設定中設定 MCP
在本機開發 MCP	否（Claude 會啟動它）	將設定指向 Python 路徑
手動測試 CLI	是	使用終端機執行
使用 Docker	是	執行 Docker 容器

使用 MCP Server

一旦您的 MCP 用戶端（Claude/Cursor）已設定並執行，您就可以開始查詢您的 Keboola 資料：

驗證您的設定

您可以從一個簡單的查詢開始，以確認一切正常運作：

What buckets and tables are in my Keboola project?

您可以做什麼的範例

資料探索：

「哪些資料表包含客戶資訊？」
「執行查詢以找出營收前 10 名的客戶」

資料分析：

「分析上一季各區域的銷售資料」
「找出客戶年齡與購買頻率之間的關聯」

資料管線：

「建立一個 SQL 轉換，將客戶與訂單資料表進行聯結」
「為我的 Salesforce 元件啟動資料擷取任務」

相容性

MCP 用戶端支援

MCP 用戶端	支援狀態	連線方式
Claude (Desktop & Web)	✅ 支援	stdio
Cursor	✅ 支援	stdio
Windsurf, Zed, Replit	✅ 支援	stdio
Codeium, Sourcegraph	✅ 支援	Streamable HTTP
自訂 MCP 用戶端	✅ 支援	Streamable HTTP 或 stdio

支援的工具

注意： 您的 AI 代理程式會自動適應新的工具。

如需可用工具的完整清單，包含詳細描述、參數和使用範例，請參閱 TOOLS.md。

疑難排解

常見問題

問題	解決方案
驗證錯誤	驗證 `KBC_STORAGE_TOKEN` 是否有效
工作區問題	確認 `KBC_WORKSPACE_SCHEMA` 是否正確
連線逾時	檢查網路連線

開發

安裝

基本設定：

uv sync --extra dev

使用基本設定，您可以使用 uv run tox 來執行測試並檢查程式碼風格。

建議設定：

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

使用建議設定，將安裝用於測試和程式碼風格檢查的套件，這讓像是 VsCode 或 Cursor 的 IDE 可以在開發期間檢查程式碼或執行測試。

整合測試

若要在本機執行整合測試，請使用 uv run tox -e integtests。注意：您需要設定下列環境變數：

INTEGTEST_POOL_STORAGE_API_URL
INTEGTEST_STORAGE_TOKENS
INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

若要取得這些值，您需要專門用於整合測試的 Keboola 專案。每個測試工作階段都會建立自己的唯讀工作區，因此不需要設定工作區結構描述。請參閱 integtests/README.md 以取得詳細的設定指示和設計文件。

更新 `uv.lock`

如果您已新增或移除相依性，請更新 uv.lock 檔案。在建立發行版本時（uv lock --upgrade），也請考慮使用較新的相依性版本更新鎖定。

更新工具文件

當您對任何工具描述（工具函式中的 docstring）進行變更時，您必須重新產生 TOOLS.md 文件檔案以反映這些變更：

uv run python -m src.keboola_mcp_server.generate_tool_docs

發行

我們不會為每個合併的 PR 發行版本。工作會持續落在主幹（main）上，我們會定期發行，以便在變更經過共同重新測試之後再發布，這樣可以避免破壞使用者的現有設定。

發行版本是透過推送一個或兩個 git 標籤來建立的：

vX.Y.Z — MCP Server 發行版本（永遠）
agent-vX.Y.Z — In Platform Agent 發行版本（僅在同時發行 Agent 時）

任一標籤都會觸發 release.yml CI，它會建置並發布 Docker 映像。KaiBench 僅在生產環境的 vX.Y.Z 標籤上執行（不在 agent-vX.Y.Z 上執行，也不在 -dev. 預先發行版本上執行）。請使用 release-notes 技能 — 它會準備發行說明和草稿 PR，並逐步引導您標記 vX.Y.Z 和 agent-vX.Y.Z。

支援與意見回饋

⭐ 取得協助、回報錯誤或要求功能的主要方式是在 GitHub 上開啟 issue。 ⭐

開發團隊會積極監控 issues，並會盡快回覆。如需 Keboola 的一般資訊，請使用下列資源。

資源

使用者文件
開發者文件
Keboola 平台
Issue 追蹤器 ← MCP Server 的主要聯絡方式