Keboola

官方

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

你可以用 Keboola MCP 做什么？

查询存储表 — 让助手直接查询表，并管理 Keboola 项目中的表或存储桶描述。
构建 SQL 转换 — 用自然语言描述转换，让助手创建 SQL 转换。
运行和检查作业 — 启动组件或转换作业，并获取其执行详情。
管理组件和流程 — 创建、列出和检查提取器、写入器、数据应用和转换配置，并构建工作流管道。
搜索项目元数据 — 使用自然语言搜索、读取和更新项目文档及对象元数据。
在开发分支中工作 — 将所有操作限定在选定的开发分支中，确保更改不会影响生产环境。

文档

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 Agent 和 MCP Server，你可以：

存储：直接查询表，并管理表或存储桶的描述
组件：创建、列出和检查提取器、写入器、数据应用和转换配置
SQL：使用自然语言创建 SQL 转换
作业：运行组件和转换，并获取作业执行详情
流程：使用 Conditional Flows 和 Orchestrator Flows 构建和管理工作流管道。
数据应用：创建、部署和管理 Keboola Data Apps，以展示对存储数据的查询结果 — python-js 应用可部署在 Keboola 管理的代码库或客户的 GitHub 代码库上（通过组织的 GitHub 连接克隆，不存储凭据），也可部署 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 账户登录。之后，在对话中选择要使用的项目（例如“列出我的 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

按区域划分的命令：

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

身份验证：

首次在 Claude Code 中使用 Keboola MCP Server 时，系统会打开浏览器窗口，提示你：

使用 Keboola 账户登录
授权连接

完成身份验证后，你就可以直接在 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。每个请求都必须通过请求头 X-Branch-Id: <branchId> 包含分支 ID，否则 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

延迟加载工具

请求头	说明	示例
`X-Deferred-Tools`	以逗号分隔的工具列表，这些工具会通过 `_meta["anthropic/alwaysLoad"] = false` 列出	`run_sync_action,get_flow_schema`

使用 alwaysLoad: true 注册服务器的 Claude Code / Claude Agent SDK 客户端会将这些工具保留为延迟加载，供工具搜索使用，而不是预先加载其定义。此请求头只会更改 tools/list 元数据，不会隐藏工具或授予工具使用权限。请求头为空或包含未知工具名称时，不会产生任何变化。

详细文档请参阅 developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control。

行级和列级安全

行级和列级策略是 Keboola Metastore 对象（rls-policy、cls-policy），使用 kbagent rls / kbagent cls 编写。此服务器既不读取也不应用这些策略。在启用了 row-level-security 功能的项目中，服务器会创建其工作区（keboola.mcp-server-tool 组件的 mcp-workspace-<hex> 配置），并使用 Connection 登录类型 governed。受治理的工作区不包含凭据：只有 Query Service 可以读取它，并且 Query Service 会根据项目策略筛选每个 query_data 结果。此服务器不会重写查询，也没有回退方案：Query Service 拒绝的内容， query_data 会作为错误返回。

启用条件。 此服务器只检查项目功能；Connection 无需任何功能或角色即可创建受治理工作区（Snowflake 或 BigQuery，无需公钥）。堆栈的 Connection 必须支持项目后端对应的登录类型 governed：不支持该类型的堆栈会拒绝创建，之后所有需要工作区的工具都会失败（不会回退到普通工作区）。旧的普通 MCP 工作区不会被删除：启用该功能后，服务器会跳过它。启用该功能后，只有受治理工作区才接受 workspace_schema 或 X-Workspace-Id 固定指定（普通工作区会绕过策略），因此，指向旧工作区或数据应用自身普通工作区的固定指定会被拒绝；请删除旧工作区。
默认拒绝。 对于受治理工作区，如果没有任何 rls-policy 适用于某张表，Query Service 会拒绝访问该表（ "*" 规则会向所有已识别的读取者开放表）；仅有 cls-policy 不会授予任何行的访问权限。不读取任何表的语句（SELECT 1）可以运行。拒绝结果会以 Row-level security does not allow this query 的形式返回给代理。
读取者身份。 Query Service 会从项目管理员自己的令牌中解析读取者身份：此服务器转发的程序化令牌（kbc_at_ / kbc_pat_，包括多项目范围的子 PAT，并通过 X-KBC-ProjectId 发送），或管理员自己的主 Storage 令牌。任何其他令牌（集成、数据应用、Kai）都无法标识最终用户，没有经过验证的身份，因此无法读取受治理表中的任何内容。组规则永远不会匹配（身份不包含任何组）。
绑定。 如果没有绑定，工作区会获得项目的所有策略，此服务器不会创建绑定。若要仅向工作区授予部分策略，请将策略绑定到其 KID：KID:<stack id>:project-<project id>:workspace-<workspace id> （默认分支的工作区；分支工作区还需要 branch-<branch id>，然后是 project）。堆栈 ID 是 Query Service 配置使用的 ID（QUERY_RLS_STACK_ID，例如 dev-keboola-aws-eu-west-1），工作区 ID 可在 get_project_info 输出中找到，而 kbagent rls bind --project P --workspace-id WS --rls-policy ID --stack-id S 用于写入绑定。绑定只会缩小策略范围，并在下一次查询时生效；它不会随会话切换到其他工作区：分支会话或重新创建的工作区会有新的 KID，并重新获得所有策略。
限制。 如果没有为数据应用单独配置工作区，服务器工作区 ID 也会作为 WORKSPACE_ID 提供给数据应用；应用使用自己的令牌进行查询，没有经过验证的身份，因此无法读取受治理表中的任何内容。
元数据。 元数据工具只会显示 Query Service 允许读取者读取的内容。get_tables 和 search （此时不会使用全局搜索，因为其计数包含隐藏表）会省略读取者无权读取的表；如果通过 ID 请求某张表，get_tables 会报告未找到该表。带有列策略的表只会显示策略允许的列（主键和 search 的匹配结果中也只包含这些列）。可读取的表不会显示行数和大小，因为这些统计值会计入被行策略隐藏的行。get_buckets 仍会列出所有存储桶，但不会显示表数量和大小，因为这些统计值会计入隐藏表。这需要 Query Service 端点 POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope，并采用失败时关闭的方式：如果 Query Service 无法确定结果，受治理项目中的工具会返回错误，且只包含简短消息，不包含任何表。未启用该功能的项目不受影响，也不会产生额外调用。

本地 MCP Server 设置（自定义或开发方式）

在自己的计算机上运行 MCP Server，以获得完全控制权并便于开发。如果你想自定义工具、在本地调试或快速迭代，请选择此方式。你需要安装服务器、完成身份验证（一次性浏览器登录，无需粘贴令牌），然后启动服务器。此方式灵活性最高（可自定义工具、本地记录日志、离线迭代），但需要手动设置，并由你自行管理更新和密钥。服务器支持多种传输选项，启动服务器时可通过提供 --transport <transport> 参数来选择：

stdio - 未指定 --transport 时的默认选项。标准输入/输出，通常用于单客户端本地部署。
streamable-http - 通过 HTTP 在远程运行服务器，并使用双向流式通道，让客户端和服务器能够持续交换消息。通过 /mcp 连接（例如 http://localhost:8000/mcp）。
http-compat - streamable-http 的别名，为向后兼容而保留。

要使用你的 Keboola 项目，服务器需要两项信息：你的 Keboola Region（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。

这需要使用启用了代理配置功能的堆栈；在其他堆栈上，该工具会提示此功能不可用。

无需运行服务器，也可以通过远程托管的 MCP 服务器实现同样的功能，前提是其运营方已启用此功能（KBC_ALLOW_ANONYMOUS_PROVISIONING）：此类部署还会提供 https://mcp.<stack>/mcp-anonymous，该端点不接受任何凭据。无需身份验证即可将客户端指向该端点，调用 create_project，然后继续使用该调用创建的项目——服务器会为你保管凭据，工具会返回一个不透明的 scope_token，供后续调用时重新发送。它使用独立 URL，因为普通的 /mcp 端点必须继续拒绝未经身份验证的请求：正是这种拒绝让 MCP 客户端知道应启动 OAuth 登录。认领项目后，切换到 /mcp，并使用现在拥有该项目的账户登录。

无法使用浏览器时进行身份验证

对于无法进行浏览器登录的容器或 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 Region）

你的 Keboola Region 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.11+
拥有具有管理员权限的 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 服务器。

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

Claude Desktop 配置

打开 Claude（屏幕左上角）-> Settings → Developer → Edit Config（如果找不到 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_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

配置文件位置：

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

Cursor 配置

打开 Settings → MCP
点击“+ Add new global MCP Server”
使用以下设置进行配置：

{
  "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 服务器代码的开发者：

克隆代码仓库并设置本地环境
配置 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 Server

配置并运行 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 代理会自动适配新工具。

如需查看可用工具的完整列表及其详细说明、参数和使用示例，请参阅 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，以构建并发布 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 Server 的主要联系渠道