Keboola MCP Server

Kepoola MCP服务器

连接您的AI代理、MCP客户端(光标, 克劳德, 帆板运动, VS Code …）和Keboola的其他人工智能助手。公开数据、转换、SQL查询和作业触发器——不需要粘合代码。在代理需要的时间和地点向他们提供正确的数据。

概述

Kepoola MCP服务器是Kepoola项目和现代人工智能工具之间的开源桥梁。它将Keoola的功能（如存储访问、SQL转换和作业触发器）转化为Claude、Cursor、CrewAI、LangChain、Amazon Q等的可调用工具。

• 快速开始
• 本地设置

特性

使用AI代理和MCP服务器，您可以：

• 存储：直接查询表并管理表或存储桶描述
• 组件：创建、列出和检查提取器、写入器、数据应用程序和转换配置
• 结构化查询语言：使用自然语言创建SQL转换
• 乔布斯：运行组件和转换，并检索作业执行详细信息
• 流动：使用条件流和编排器流构建和管理工作流管道。
• 数据应用程序：创建、部署和管理Kepoola Streamlit数据应用程序，显示您对存储数据的查询。
• 元数据：使用自然语言搜索、阅读和更新项目文档和对象元数据
• 开发分支：在生产之外的开发分支中安全工作，所有操作都在所选分支的范围内。

______________________________________________________________________

🚀 快速入门：远程MCP服务器（最简单的方法）

使用Kepoola MCP服务器的最简单方法是通过我们的 远程MCP服务器。此托管解决方案消除了对本地设置、配置或安装的需要。

什么是远程MCP服务器？

我们的远程服务器托管在每个多租户Kepoola堆栈上，并支持OAuth身份验证。您可以从任何支持远程Streamable HTTP连接和OAuth身份验证的AI助手连接到它。

如何连接

1. 获取远程服务器URL：导航到您的Keoola项目设置→ MCP Server 标签
2. 复制服务器URL：看起来会像 https://mcp..keboola.com/mcp
3. 配置您的AI助手：将URL粘贴到AI助手的MCP设置中
4. 验证：系统将提示您使用Kepoola帐户进行身份验证并选择您的项目

支持的客户

• 光标：在项目的MCP服务器设置中使用“在光标中安装”按钮，或单击

这个按钮

• 克劳德桌面版：通过设置添加集成→ 集成
• 克劳德代码：使用安装 claude mcp add --transport http keboola （详见下文）
• 帆板运动：使用远程服务器URL进行配置
• 制造：使用远程服务器URL进行配置
• 其他MCP客户端：使用远程服务器URL进行配置

Claude代码设置

Claude Code是一个命令行界面工具，允许您使用终端与Claude交互。您可以使用一个简单的命令安装Kepoola MCP Server集成。

安装：

在终端中运行以下命令，替换 `` 与您的Keboola地区：

claude mcp add --transport http keboola https://mcp..keboola.com/mcp

区域特定命令：

用途：

安装后，您可以通过键入以下命令在Claude Code中使用Kepoola MCP服务器 /mcp 在您的对话中，选择您想要使用的Keboola工具。

身份验证：

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

1. 使用您的Keboola帐户登录
2. 选择要连接的项目
3. 授权连接

身份验证后，您可以直接从Claude Code开始使用Kepoola工具。

有关详细的设置说明和特定于地区的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: ，否则MCP服务器默认使用生产分支。这应该由AI客户端或处理服务器连接的环境来管理。

工具授权和访问控制

使用基于HTTP的传输（Streamable HTTP）时，您可以使用HTTP标头控制客户端可用的工具。这对于限制AI代理功能或执行合规策略非常有用。

授权标头

过滤器行为

过滤器按顺序应用：允许→ 只读交叉口→ 不允许排除。空标题=无限制。

只读工具

只读工具是那些带有注释的工具 readOnlyHint=True。这些工具仅检索信息，而不会对您的Kepoola项目进行任何更改。有关只读工具的当前列表，请参阅 TOOLS.md 该文件是实际工具集的自动生成快照。

示例：只读访问

X-Read-Only-Mode: true

有关详细文档，请参阅 developers.keboola.com/integration/mcp/#工具授权和访问控制.

______________________________________________________________________

本地MCP服务器设置（自定义或开发方式）

在您自己的机器上运行MCP服务器，以实现完全控制和轻松开发。当您想要自定义工具、在本地调试或快速迭代时，请选择此选项。您将克隆仓库，根据服务器传输通过环境变量或标头设置Kepoola凭据，安装依赖项，并启动服务器。这种方法提供了最大的灵活性（自定义工具、本地日志记录、离线迭代），但需要手动设置，您可以自己管理更新和机密。

服务器支持多个 运输 选项，可以通过提供 --transport 启动服务器时的参数：

• stdio -默认情况下 --transport 未指定。标准输入/输出，通常用于单个客户端的本地部署。
• streamable-http -通过HTTP和双向流通道远程运行服务器，允许客户端和服务器持续交换消息。通过连接 /mcp（例如。，http://localhost:8000/mcp).
• http-compat -别名 streamable-http，保持向后兼容性。

对于客户端-服务器通信，必须提供Kepoola凭据，以便在Kepoola地区使用您的项目。需要以下内容： KBC_STORAGE_TOKEN, KBC_STORAGE_API_URL, KBC_WORKSPACE_SCHEMA 并且可选 KBC_BRANCH_ID。您可以通过两种方式提供这些：

• 个人使用（主要用于stdio传输）：在启动服务器之前设置环境变量。所有请求都将重用这些预定义的凭据。
• 对于多用户使用：在请求头中包含变量，以便每个请求都使用随附的凭据。

KBC_STORAGE_TOKEN

这是您的Kepoola身份验证令牌：

有关如何创建和管理Storage API令牌的说明，请参阅 Keboola官方文件.

备注：如果希望MCP服务器具有有限的访问权限，请使用自定义存储令牌，如果希望MCP访问项目中的所有内容，请使用主令牌。

KBC_WORKSPACE_SCHEMA

这标识了Kepoola中的工作区，用于SQL查询。然而，这是 仅当您使用自定义存储令牌时才需要 代替主令牌：

• 如果使用 主令牌：工作区是在幕后自动创建的
• 如果使用 自定义存储令牌：按照这个 Keboola指南 获取KBC_WORKSPACE_SCHEMA

备注：手动创建工作区时，选中“授予对所有项目数据的只读访问权限”选项

备注：KBC_WORKSPACE_SCHEMA在BigQuery工作区中称为数据集名称，您只需单击连接并复制数据集名称

KBC_STORAGE_API_URL（Keboola地区）

您的Keboola Region API URL取决于您的部署区域。登录Kepoola项目时，您可以通过查看浏览器中的URL来确定您的地区：

KBC_BRANC_ID（可选）

对特定对象进行操作 Keboola开发分公司，使用设置分支ID KBC_BRANCH_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:

或 KBC_BRANCH_ID: `.

安装

确保你有：

• \[\]已安装Python 3.10+
• \[\]以管理员权限访问Kepoola项目
• \[\]您首选的MCP客户端（Claude、Cursor等）

备注：确保你有 uv 安装。MCP客户端将使用它自动下载并运行Kepoola 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

*视窗*:

# 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

有关更多安装选项，请参阅 官方紫外线文件.

运行Keoola MCP服务器

根据您的需求，有四种方法可以使用Kepoola MCP服务器：

选项A：集成模式（推荐）

在此模式下，Claude或Cursor会自动为您启动MCP服务器。 您不需要在终端中运行任何命令.

1. 使用适当的设置配置您的MCP客户端（Claude/Cursor）
2. 客户端将在需要时自动启动MCP服务器

Claude桌面配置

1. 转到Claude（屏幕左上角）->设置→ 开发者→ 编辑配置（如果你没有看到claude_desktop_Config.json，请创建它）
2. 添加以下配置：
3. 重新启动Claude桌面以使更改生效

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --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
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

光标配置

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

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --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个字符以内，因此较长的名称可能会在游标中过滤掉，并且不会显示给代理。

Windows WSL的光标配置

使用Cursor AI从Windows 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 ",
          "'"
      ]
    }
  }
}

方案B：地方发展模式

对于从事MCP服务器代码本身的开发人员：

1. 克隆存储库并设置本地环境
2. 配置Claude/Cursor以使用本地Python路径：

{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server --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 将集装箱的港口映射到其他地方。

我需要自己启动服务器吗？

使用MCP服务器

配置并运行MCP客户端（Claude/Cursor）后，您可以开始查询Kepoola数据：

验证您的设置

您可以从一个简单的查询开始，确认一切正常：

What buckets and tables are in my Keboola project?

你能做什么的例子

数据探索：

• “哪些表包含客户信息？”
• “运行查询以查找按收入排名前10的客户”

数据分析：

• “按地区分析我上一季度的销售数据”
• “找出客户年龄和购买频率之间的相关性”

数据管道：

• “创建连接客户表和订单表的SQL转换”
• “启动Salesforce组件的数据提取作业”

兼容性

MCP客户端支持

支持的工具

注： 您的AI代理将自动适应新工具。

有关可用工具的完整列表，包括详细说明、参数和使用示例，请参阅 TOOLS.md.

故障排除

常见问题

发展

安装

基本设置：

uv sync --extra dev

使用基本设置，您可以使用 uv run tox 运行测试并检查代码风格。

推荐设置：

uv sync --extra dev --extra tests --extra integtests --extra codestyle

使用推荐的设置，将安装用于测试和代码风格检查的包，这允许IDE像 VsCode或Cursor用于在开发过程中检查代码或运行测试。

集成测试

要在本地运行集成测试，请使用 uv run tox -e integtests. 注意：您需要设置以下环境变量：

• INTEGTEST_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_WORKSPACE_SCHEMAS

为了获得这些值，您需要一个专门的Kepoola项目进行集成测试。 看 integtests/README.md 有关详细的设置说明和设计文档。

更新 uv.lock

更新 uv.lock 如果您添加或删除了依赖项，请使用文件。还可以考虑使用较新的依赖项更新锁 创建发布时的版本(uv lock --upgrade).

更新工具文档

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

uv run python -m src.keboola_mcp_server.generate_tool_docs

支持和反馈

⭐ 获取帮助、报告错误或请求功能的主要方式是 . ⭐

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

资源

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

连接

• 领英
• 推特
• 更新日志