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 认证。您可以从任何支持远程可流式 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

特定区域的命令：

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

有关详细的设置说明和特定区域的 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 的传输（可流式 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 欧盟	`https://connection.europe-west3.gcp.keboola.com`
Google Cloud 美国	`https://connection.us-east4.gcp.keboola.com`
Azure 欧盟	`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 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_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）。

更新工具文档

当你对任何工具描述（工具函数中的文档字符串）进行更改时，你必须重新生成 TOOLS.md 文档文件以反映这些更改：

uv run python -m src.keboola_mcp_server.generate_tool_docs

发布

我们不会为每个合并的 PR 都进行发布。工作成果会持续合并到主干（main），我们会定期在更改经过重新测试后一起发布——这样可以避免破坏用户正常工作的设置。

发布是通过推送一个或两个 git 标签来完成的：

vX.Y.Z — MCP 服务器发布（始终需要）
agent-vX.Y.Z — 平台内代理发布（仅在代理也需要发布时）

任一标签都会触发 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 平台
问题跟踪器 ← MCP 服务器的主要联系方式

文档