Keboola

官方

在单一直观平台上构建强大的数据工作流、集成和分析。

你可以用 Keboola MCP 做什么？

查询存储表 — 让助手探索存储桶和表，或运行 SQL 查询以按收入查找顶级客户。
创建 SQL 转换 — 用自然语言描述转换，例如关联客户表和订单表，并让系统为您构建。
管理组件和作业 — 列出提取器和写入器，启动数据提取作业，并检索管道的执行详情。
构建工作流 — 创建和管理条件流或编排器流，以自动化多步骤数据管道。
部署数据应用 — 创建和管理 Streamlit 数据应用，在存储数据上显示查询结果。
在开发分支中工作 — 将所有操作限定在开发分支内，安全测试更改而不影响生产环境。

文档

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 账户登录。之后在对话中选择要处理的项目（例如“列出我的 Keboola 项目”/“使用项目 X”）

支持的客户端

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

区域特定命令：

区域	安装命令
美国弗吉尼亚 AWS	`claude mcp add --transport http keboola https://mcp.keboola.com/mcp`
美国弗吉尼亚 GCP	`claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp`
欧盟法兰克福 AWS	`claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp`
欧盟爱尔兰 Azure	`claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp`
欧盟法兰克福 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 工具。项目选择在之后的对话中进行——只需询问 Claude 要使用哪个 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。分支 ID 必须使用标头 X-Branch-Id: <branchId> 包含在每个请求中，否则 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 服务器，以获得完全控制并便于开发。当您想要自定义工具、本地调试或快速迭代时，请选择此方式。您将安装服务器、进行认证（一次性浏览器登录——无需粘贴令牌），然后启动它。这种方法提供了最大的灵活性（自定义工具、本地日志记录、离线迭代），但需要手动设置，并且您需要自行管理更新和密钥。

服务器支持多种传输选项，可以通过在启动服务器时提供 --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 标头将被忽略（记录警告）。没有自己固定值的服务器（共享多用户情况）会继续按请求从请求中获取固定值，如下所述。

这将打开您的浏览器以登录 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 将查询固定到一个特定的、已存在的工作区，而不是上述基于模式的查找，并且当两者都设置时优先于 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 北美	`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 服务器。

在终端中登录一次，以便存储会话（客户端在后台启动服务器，此时浏览器无法打开）：
```
uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
```
使用以下设置配置您的 MCP 客户端（Claude/Cursor）——仅需 KBC_STORAGE_API_URL。
客户端将在需要时自动启动 MCP 服务器。

Claude Desktop 配置

前往 Claude（屏幕左上角）-> 设置 → 开发者 → 编辑配置（如果看不到 claude_desktop_config.json，请创建它）
添加以下配置：
重启 Claude 桌面版以使更改生效

{
  "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 配置

前往设置 → MCP
点击“+ 添加新的全局 MCP 服务器”
使用以下设置进行配置：

{
  "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 中被过滤掉，并且不会显示给代理。

适用于 Windows WSL 的 Cursor 配置

当从 Windows 子系统 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 服务器代码本身的开发者：

克隆仓库并设置本地环境
配置 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 传输，并在 /mcp 处监听 localhost:8000 上的传入连接。您可以使用 --port 和 --host 参数使其在其他位置监听。

选项 D：使用 Docker

容器无法打开浏览器，因此请使用令牌进行身份验证（请参阅无需浏览器进行身份验证）：将 KBC_STORAGE_TOKEN 设置为 Keboola 访问/个人访问令牌，并将 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 传输，并在 /mcp 处监听 localhost:8000 上的传入连接。您可以更改 -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。

故障排除

常见问题

问题	解决方案
身份验证错误	重新运行 `keboola_mcp_server login`（或者，如果使用令牌进行身份验证，请验证令牌和 `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）。

更新工具文档

当您对任何工具描述（工具函数中的文档字符串）进行更改时，必须重新生成 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，该 CI 会构建并发布 Docker 镜像。KaiBench 仅在生产的 vX.Y.Z 标签上运行（不在 agent-vX.Y.Z 上，也不在 -dev. 预发布版本上）。请使用 release-notes 技能——它会准备发布说明和草稿 PR，并引导您完成 vX.Y.Z 和 agent-vX.Y.Z 的标签标记。

支持和反馈

⭐ 获取帮助、报告错误或请求功能的主要方式是在 GitHub 上打开问题。⭐

开发团队会积极监控问题并尽快响应。有关 Keboola 的一般信息，请使用以下资源。

资源

用户文档
开发者文档
Keboola 平台
问题跟踪器 ← MCP 服务器的主要联系方式