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 代理和 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 服务器设置中使用“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

区域特定命令：

区域	安装命令
美国弗吉尼亚 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`

用法：

安装后，您可以通过在对话中键入 /mcp 并选择要使用的 Keboola 工具，在 Claude Code 中使用 Keboola MCP Server。

身份验证：

当您首次在 Claude Code 中使用 Keboola MCP Server 时，将打开一个浏览器窗口，提示您：

使用您的 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。分支 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 Server 设置（自定义或开发方式）

在您自己的机器上运行 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_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 服务器具有有限访问权限，请使用自定义存储令牌；如果您希望 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 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 服务器。您无需在终端中运行任何命令。

使用适当的设置配置您的 MCP 客户端（Claude/Cursor）
客户端将在需要时自动启动 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_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 中被过滤掉，并且不会显示给 Agent。

适用于 Windows WSL 的 Cursor 配置

当通过 Cursor AI 从 Windows Subsystem for Linux 运行 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 发布（仅当 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 上打开 issue。⭐

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

资源

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