Keboola MCP Server

Keboola MCP 伺服器

將您的 AI 代理、MCP 客戶端（Cursor、Claude、Windsurf、VS Code 等）及其他 AI 助手連接到 Keboola。無需編寫膠水程式碼，即可公開資料、轉換、SQL 查詢和工作觸發器。在代理需要時，將正確的資料傳遞到正確的位置。

概覽

Keboola MCP 伺服器是您的 Keboola 專案與現代 AI 工具之間的開源橋樑。它將 Keboola 的功能（例如儲存空間存取、SQL 轉換和工作觸發器）轉換為可供 Claude、Cursor、CrewAI、LangChain、Amazon Q 等工具呼叫的工具。

快速入門
本機設定

功能

透過 AI 代理和 MCP 伺服器，您可以：

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

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

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

什麼是遠端 MCP 伺服器？

我們的遠端伺服器託管在每個多租戶 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 伺服器設定中的「在 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 伺服器整合。

安裝：

在您的終端機中執行以下指令，將 <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 伺服器。

驗證：

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

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

驗證後，您可以直接從 Claude Code 開始使用 Keboola 工具。

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

使用開發分支

您可以在 Keboola 開發分支中安全地工作，而不會影響您的生產資料。遠端託管的 MCP 伺服器會遵循 KBC_BRANCH_ID 參數，並將所有操作限定在指定的分支內。您可以在 UI 中導覽至開發分支時，從 URL 中找到開發分支 ID，例如：https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard。每個請求中必須使用標頭 X-Branch-Id: <branchId> 包含分支 ID，否則 MCP 伺服器預設使用生產分支。這應由 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 伺服器設定（自訂或開發方式）

在您自己的機器上執行 MCP 伺服器，以獲得完全控制和輕鬆開發。當您想要自訂工具、在本機除錯或快速迭代時，請選擇此方式。您將複製儲存庫，根據伺服器傳輸方式透過環境變數或標頭設定 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_TOKEN

這是您的 Keboola 驗證權杖：

如需有關如何建立和管理儲存 API 權杖的說明，請參閱官方 Keboola 文件。

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

KBC_WORKSPACE_SCHEMA

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

如果使用主權杖：工作區會在幕後自動建立
如果使用自訂儲存權杖：請遵循此 Keboola 指南來取得您的 KBC_WORKSPACE_SCHEMA

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

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

KBC_STORAGE_API_URL（Keboola 區域）

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

區域	API URL
AWS 北美	`https://connection.keboola.com`
AWS 歐洲	`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 伺服器會將其功能限定在指定的分支內，確保所有變更保持隔離，不會影響生產分支。

如果未提供，伺服器預設使用生產分支。
對於開發工作，請將 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 伺服器。 安裝 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 伺服器

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

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

在此模式下，Claude 或 Cursor 會自動為您啟動 MCP 伺服器。您無需在終端機中執行任何指令。

使用適當的設定來配置您的 MCP 客戶端（Claude/Cursor）
客戶端將在需要時自動啟動 MCP 伺服器

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 伺服器」
使用以下設定進行配置：

{
  "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 伺服器使用簡短、描述性的名稱。由於完整的工具名稱包含伺服器名稱，且必須保持在約 60 個字元以內，因此較長的名稱可能會在 Cursor 中被過濾掉，並且不會顯示給代理。

適用於 Windows WSL 的 Cursor 設定

從 Windows 子系統 Linux 版搭配 Cursor AI 執行 MCP 伺服器時，請使用此設定：

{
  "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 伺服器程式碼本身的開發人員：

複製儲存庫並設定本地環境
設定 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 伺服器

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

驗證您的設定

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

What buckets and tables are in my Keboola project?

您可以執行的操作範例

資料探索：

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

資料分析：

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

資料管線：

「建立一個聯結客戶和訂單資料表的 SQL 轉換」
「啟動我的 Salesforce 元件的資料擷取作業」

相容性

MCP 客戶端支援

MCP 客戶端	支援狀態	連線方式
Claude（桌面版與網頁版）	✅ 支援	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 伺服器發行版本（總是會推送）
agent-vX.Y.Z — In Platform 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。⭐

開發團隊會積極監控 issue，並會盡快回應。如需關於 Keboola 的一般資訊，請使用以下資源。

資源

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

文件