Keboola

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 代理和 MCP Server，您可以：

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

---

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

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

什麼是遠端 MCP Server？

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

如何連接

1. 取得您的遠端伺服器 URL：前往您的 Keboola 專案設定 → MCP Server 標籤
2. 複製伺服器 URL：它看起來像 https://mcp.<YOUR_REGION>.keboola.com/mcp
3. 設定您的 AI 助手：將 URL 貼到您 AI 助手的 MCP 設定中
4. 驗證：系統會提示您使用 Keboola 帳戶登入。之後在對話中選擇要處理的專案（例如「列出我的 Keboola 專案」/「使用專案 X」）

支援的用戶端

• 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 時，會開啟瀏覽器視窗提示您：

1. 使用您的 Keboola 帳戶登入
2. 授權連線

驗證後，您就可以直接從 Claude Code 開始使用 Keboola 工具。專案選擇在之後的對話中進行——只需詢問 Claude 要使用哪些 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，以獲得完全控制和輕鬆開發。當您想要自訂工具、在本機除錯或快速迭代時，請選擇此方式。您將安裝伺服器、驗證（一次性瀏覽器登入——無需貼上權杖），然後啟動它。此方法提供最大的靈活性（自訂工具、本機記錄、離線迭代），但需要手動設定，且您需自行管理更新和密碼。

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

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

要使用您的 Keboola 專案，伺服器需要兩件事：您的 Keboola 區域（KBC_STORAGE_API_URL）和一種驗證方式。建議的方式是一次性瀏覽器登入——您永遠不需要建立、複製或貼上權杖。可選擇設定 KBC_BRANCH_ID 以在開發分支中工作。

有些變數不會從請求標頭取得：

• 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_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA：與上述 Storage API URL 的概念相同——使用自己的工作區釘選啟動的伺服器（透過任一變數或 --workspace-id）會為每個請求保留該釘選；要求不同工作區的 X-Workspace-Id 或 X-Workspace-Schema 標頭會被忽略（會記錄警告）。沒有自己釘選的伺服器（共用多使用者案例）會繼續按請求從請求中取得釘選，如下所述。

登入

使用瀏覽器登入一次；伺服器會儲存工作階段並自動重新整理，因此無需管理權杖：

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

這會開啟您的瀏覽器登入 Keboola，然後將堆疊範圍的工作階段儲存到 ~/.keboola/mcp/credentials.json（僅您可讀取，每個堆疊一個條目）。之後，僅設定 KBC_STORAGE_API_URL 即可啟動伺服器——無需權杖。之後在對話中選擇要處理的專案（get_accessible_projects / set_project_scope），而非在登入時選擇。

命令	功能
login --api-url <url>	登入堆疊
login --force	再次登入 / 切換帳戶
login --show-token	列印目前的工作階段權杖（除錯）
logout [--api-url <url>] [--all]	移除堆疊的已儲存工作階段（或所有堆疊）

當您在互動式終端機中透過 stdio 啟動伺服器且沒有已儲存的工作階段時，它會在首次啟動時自動執行此瀏覽器登入。MCP 用戶端（Claude、Cursor 等）會在背景啟動伺服器，而背景無法開啟瀏覽器，因此請先自行執行一次 login。

在沒有 Keboola 帳戶的情況下啟動

您也可以僅設定 KBC_STORAGE_API_URL 且不帶任何憑證來啟動伺服器。它會以引導模式啟動：需要 Keboola 存取權限的工具會說明如何取得憑證，而有一個工具無需憑證即可運作——create_project。它會建立一個新的 Keboola 專案，將工作階段登入到該專案，並傳回確認 URL。在瀏覽器中開啟該 URL 並登入，即可使該專案永久屬於您；在此之前它是暫時的，Keboola 可能會回收它，而一旦您確認，該工具建立的工作階段就會被撤銷，您將繼續使用自己的 login。

這需要啟用代理佈建的堆疊；在其他地方，該工具會回報其不可用。

在沒有瀏覽器的情況下驗證

對於無法進行瀏覽器登入的容器或 CI，請直接提供 Keboola 存取或個人存取權杖——設定 KBC_STORAGE_TOKEN（環境變數）或傳送 X-StorageAPI-Token 標頭——並搭配 KBC_PROJECT_ID（或 X-KBC-ProjectId 標頭）來選擇專案。在 HTTP 傳輸上，這些可以按請求作為標頭提供，因此每個請求都攜帶自己的憑證。

KBC_WORKSPACE_ID

透過 ID 將查詢釘選到一個特定的、已存在的工作區，而非上述的基於 schema 的查詢，並且當兩者都設定時優先於 KBC_WORKSPACE_SCHEMA。這是 Data App / kai-agent 呼叫者提供的選項，作為 X-Workspace-Id 標頭，以便嵌入在該應用程式中的 Kai 僅透過自己的工作區進行查詢。

透過 KBC_WORKSPACE_ID 環境變數、--workspace-id CLI 旗標或（按請求，適用於多使用者部署）X-Workspace-Id 標頭設定。

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 伺服器會將其功能限定於指定的分支，確保所有變更保持隔離，不會影響生產分支。

• 若未提供，伺服器預設使用生產分支。
• 若進行開發工作，請將 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 伺服器。

1. 在終端機中登入一次，以便儲存工作階段（用戶端會在背景啟動伺服器，此時瀏覽器無法開啟）：

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

2. 使用下列設定設定您的 MCP 用戶端（Claude/Cursor）——僅需 KBC_STORAGE_API_URL。
3. 用戶端會在需要時自動啟動 MCP 伺服器。

Claude Desktop 設定

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

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

設定檔位置：

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

Cursor 設定

1. 前往 設定 → MCP
2. 點擊「+ 新增全域 MCP 伺服器」
3. 使用這些設定進行設定：

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

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

適用於 Windows WSL 的 Cursor 設定

當從 Windows Subsystem for 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_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

選項 B：本機開發模式

適用於開發 MCP 伺服器程式碼本身的開發人員：

1. 複製儲存庫並設定本機環境
2. 設定 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_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

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

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

# 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

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

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

選項 D：使用 Docker

容器無法開啟瀏覽器，因此請使用 token 進行驗證（請參閱 不使用瀏覽器進行驗證）：將 KBC_STORAGE_TOKEN 設定為 Keboola 存取/個人存取 token，並將 KBC_PROJECT_ID 設定為目標專案。（透過 HTTP，您可以改為在每個請求中傳遞 X-StorageAPI-Token / X-KBC-ProjectId 標頭，並省略這些設定。）

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

注意：伺服器將使用 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（Desktop 與 Web）	✅ 支援	stdio
Cursor	✅ 支援	stdio
Windsurf、Zed、Replit	✅ 支援	stdio
Codeium、Sourcegraph	✅ 支援	Streamable HTTP
自訂 MCP 用戶端	✅ 支援	Streamable HTTP 或 stdio

支援的工具

注意： 您的 AI agent 會自動適應新工具。

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

疑難排解

常見問題

問題	解決方案
驗證錯誤	重新執行 keboola_mcp_server login（或若使用 token 驗證，請確認 token 與 KBC_PROJECT_ID）
連線逾時	檢查網路連線

開發

安裝

基本設定：

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 發行版本（僅在同時發行 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 伺服器的主要聯絡方式

連結

• LinkedIn
• Twitter
• 變更日誌