Keboola MCP 服务器

这是一个用于与 Keboola Connection 交互的模型上下文协议 (MCP) 服务器。该服务器提供了从 Keboola 存储 API 列出和访问数据的工具。

要求

• Python 3.10 或更新版本
• Keboola 存储 API 令牌
• Snowflake 或 BigQuery 只读工作区

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 Keboola Explorer：

npx -y @smithery/cli install keboola-mcp-server --client claude

手动安装

首先，克隆仓库并创建虚拟环境：

git clone https://github.com/keboola/keboola-mcp-server.git
cd keboola-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip3 install -U pip 

以开发模式安装包：

pip3 install -e .

对于开发依赖项：

pip3 install -e ".[dev]"

Claude Desktop 设置

要将此服务器与 Claude Desktop 一起使用，请按照以下步骤操作：

1. 创建或编辑 Claude Desktop 配置文件：

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

2. 添加以下配置（根据您的设置调整路径）：

{
  "mcpServers": {
    "keboola": {
      "command": "/path/to/keboola-mcp-server/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server",
        "--api-url",
        "https://connection.YOUR_REGION.keboola.com"
      ],
      "env": {
        "KBC_STORAGE_TOKEN": "your-keboola-storage-token",
        "KBC_WORKSPACE_SCHEMA": "your-workspace-schema"
      }
    }
  }
}

替换：

• /path/to/keboola-mcp-server 为您实际克隆的仓库路径
• YOUR_REGION 为您的 Keboola 区域（例如 north-europe.azure 等）。如果您的区域只是 connection，则可以删除它
• your-keboola-storage-token 为您的 Keboola 存储 API 令牌
• your-workspace-schema 为您的 Snowflake 模式或 BigQuery 数据集的工作区名称

注意：如果您由于某些包兼容性问题而使用特定版本的 Python（例如 3.11），您需要将 command 更新为使用该特定版本，例如 /path/to/keboola-mcp-server/.venv/bin/python3.11

注意：可以在您的 Keboola 项目中创建工作区。这是您获取存储令牌的同一项目。工作区将提供所有必要的连接参数，包括模式或数据集名称。

1. 更新配置后：
   • 完全退出 Claude Desktop（不仅仅是关闭窗口）
   • 重新启动 Claude Desktop
   • 查看右下角是否有锤子图标，表示服务器已连接

故障排除

如果您遇到连接问题：

1. 检查 Claude Desktop 中的日志是否有任何错误消息
2. 确认您的 Keboola 存储 API 令牌正确无误
3. 确保配置中的所有路径都是绝对路径
4. 确认虚拟环境已正确激活并且所有依赖项都已安装

Cursor AI 设置

要将此服务器与Cursor AI一起使用，您有两种配置传输方法的选择：服务器发送事件（SSE）或标准输入输出（stdio）。

1. 创建或编辑Cursor AI配置文件：

   • 位置: ~/.cursor/mcp.json

2. 根据您偏好的传输方法添加以下配置之一（或全部）：

选项1：使用服务器发送事件（SSE）

{
  "mcpServers": {
    "keboola": {
      "url": "http://localhost:8000/sse?storage_token=YOUR-KEBOOLA-STORAGE-TOKEN&workspace_schema=YOUR-WORKSPACE-SCHEMA"
    }
  }
}

选项2a：使用标准输入输出（stdio）

{
  "mcpServers": {
    "keboola": {
      "command": "/path/to/keboola-mcp-server/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server",
        "--transport",
        "stdio",
         "--api-url",
         "https://connection.YOUR_REGION.keboola.com"
      ],
      "env": {
        "KBC_STORAGE_TOKEN": "your-keboola-storage-token", 
        "KBC_WORKSPACE_SCHEMA": "your-workspace-schema"         
      }
    }
  }
}

选项2b：使用WSL标准输入输出（wsl stdio）

当从Windows Subsystem for Linux运行MCP服务器并配合Cursor AI时，请使用此配置。

{
  "mcpServers": {
    "keboola": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "'source /wsl_path/to/keboola-mcp-server/.env",
        "&&",
        "/wsl_path/to/keboola-mcp-server/.venv/bin/python -m keboola_mcp_server.cli --transport stdio'"
      ]
    }
  }
}

• 其中/wsl_path/to/keboola-mcp-server/.env文件包含环境变量:

export KBC_STORAGE_TOKEN="your-keboola-storage-token"
export KBC_WORKSPACE_SCHEMA="your-workspace-schema"

替换内容：

• 将/path/to/keboola-mcp-server替换为您的克隆仓库实际路径
• 将YOUR_REGION替换为您的Keboola区域（例如north-europe.azure等）。如果您的区域仅为connection，则可以省略
• 将your-keboola-storage-token替换为您的Keboola Storage API令牌
• 将your-workspace-schema替换为您工作区的Snowflake模式或BigQuery数据集

更新配置后：

1. 重启Cursor AI
2. 如果您使用sse传输方式，请确保启动您的MCP服务器。您可以在激活了构建服务器的虚拟环境中运行以下命令来启动：

   /path/to/keboola-mcp-server/.venv/bin/python -m keboola_mcp_server --transport sse --api-url https://connection.YOUR_REGION.keboola.com
   

3. Cursor AI应能自动检测到您的MCP服务器并启用它。

BigQuery支持

如果您的Keboola项目使用BigQuery后端，则除了设置KBC_STORAGE_TOKEN和KBC_WORKSPACE_SCHEMA外，还需要设置GOOGLE_APPLICATION_CREDENTIALS环境变量。

1. 转到您的Keboola BigQuery工作区并显示其凭据（点击Connect按钮）。
2. 将凭据文件下载到本地磁盘。这是一个纯JSON文件。
3. 将下载的JSON凭据文件完整路径设置为GOOGLE_APPLICATION_CREDENTIALS环境变量。

这将赋予您的MCP服务器实例访问Google Cloud中的BigQuery工作区所需的权限。

可用工具

服务器提供了以下工具用于与Keboola Connection交互：

• 列出存储桶和表
• 获取存储桶和表信息
• 预览表数据
• 将表数据导出为CSV
• 列出组件和配置

开发

运行测试：

pytest

格式化代码：

black .
isort .

类型检查：

mypy .

许可证

MIT许可证 - 详情请参见LICENSE文件。