使用说明

项目简介

MCP Iceberg Catalog Service 是一个实现了 Model Context Protocol (MCP) 的服务器，它允许大型语言模型 (LLM) 客户端（如 Claude Desktop）通过标准化的 MCP 协议，以 SQL 接口的形式访问和操作 Apache Iceberg 数据湖。该服务器充当 LLM 与 Iceberg 数据湖之间的桥梁，使得 LLM 可以利用 Iceberg 中的数据进行上下文学习和知识检索。

主要功能点

Iceberg 数据访问: 通过 SQL 语句查询和管理 Apache Iceberg 表格数据。
SQL 接口: 支持常见的 SQL 操作，包括：
- 'LIST TABLES': 列出 Iceberg catalog 中的所有表。
- 'DESCRIBE TABLE': 查看表的 Schema、分区信息、排序规则和属性。
- 'SELECT': 从 Iceberg 表中检索数据。
- 'INSERT': 向 Iceberg 表中插入新数据。
- 'CREATE TABLE': 创建新的 Iceberg 表。
MCP 协议: 遵循 MCP 协议标准，与 LLM 客户端通过 JSON-RPC over Stdio 进行通信。
工具注册: 注册 'execute_query' 工具，允许 LLM 客户端调用执行 SQL 查询。

安装步骤

本服务主要设计用于与 Claude Desktop 等 MCP 客户端配合使用。以下是在 Claude Desktop 中安装和配置 MCP Iceberg Catalog Service 的步骤：

环境准备:
- 确保已安装 Python 3.10 或更高版本。
- 推荐使用 UV 包管理器，或者 pip。
- 确保可以访问 Iceberg REST catalog 和兼容 S3 的存储服务。

获取代码:

从 GitHub 克隆仓库代码到本地：

git clone https://github.com/ahodroj/mcp-iceberg-service.git
cd mcp-iceberg-service

或者下载仓库的 ZIP 文件并解压。

配置 Claude Desktop:
- 打开 Claude Desktop 的配置文件 'claude_desktop_config.json'。
- 在 'mcpServers' 字段下添加 'iceberg' 服务器的配置信息。

服务器配置

在 'claude_desktop_config.json' 中，'mcpServers' 字段用于配置 MCP 服务器。您需要添加如下 'iceberg' 服务器的配置：

{
  "mcpServers": {
    "iceberg": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH_TO_/mcp-iceberg-service", //  **[请替换为实际的 mcp-iceberg-service 仓库路径]**
        "run",
        "mcp-server-iceberg"
      ],
      "env": {
        "ICEBERG_CATALOG_URI" : "http://localhost:8181", // **[请替换为您的 Iceberg Catalog URI]** 例如: "http://localhost:8181"
        "ICEBERG_WAREHOUSE" : "YOUR ICEBERG WAREHOUSE NAME", // **[请替换为您的 Iceberg Warehouse 名称]** 例如: "my_warehouse"
        "S3_ENDPOINT" : "OPTIONAL IF USING S3", // **[可选，如果使用 S3，请配置 S3 Endpoint]** 例如: "s3.amazonaws.com"
        "AWS_ACCESS_KEY_ID" : "YOUR S3 ACCESS KEY", // **[您的 S3 Access Key ID]**
        "AWS_SECRET_ACCESS_KEY" : "YOUR S3 Secret Key" // **[您的 S3 Secret Access Key]**
      }
    }
  }
}

配置参数说明:

'"server name"': '"iceberg"' - 服务器名称，在 Claude Desktop 中用于标识和调用此服务器。
'"command"': '"uv"' - 启动服务器的命令，这里使用 'uv' (需提前安装 uv 包管理器，或者替换为 'python' 并调整 'args' 中的启动脚本路径)。
'"args"': 启动命令的参数列表：
- '"PATH_TO_/mcp-iceberg-service"': 请务必替换为 您本地 'mcp-iceberg-service' 仓库的绝对路径。
- '"run"': 使用 uv 运行 Python 脚本的子命令。
- '"mcp-server-iceberg"': 要运行的 Python 脚本入口点（在 'pyproject.toml' 中定义）。
'"env"': 服务器运行所需的环境变量：
- '"ICEBERG_CATALOG_URI"': 必须配置，Iceberg Catalog 的 URI 地址，例如 'http://localhost:8181'。
- '"ICEBERG_WAREHOUSE"': 必须配置，Iceberg Warehouse 的名称。
- '"S3_ENDPOINT"': 可选，如果 Iceberg Catalog 使用 S3 存储，则需要配置 S3 Endpoint。
- '"AWS_ACCESS_KEY_ID"': 必须配置 (如果 Iceberg Catalog 使用 S3 存储)，S3 Access Key ID。
- '"AWS_SECRET_ACCESS_KEY"': 必须配置 (如果 Iceberg Catalog 使用 S3 存储)，S3 Secret Access Key。

注意: 请根据您的 Iceberg 环境和 S3 配置，准确填写 'claude_desktop_config.json' 中的路径和环境变量。特别是 'PATH_TO_/mcp-iceberg-service' 需要替换为实际的本地仓库路径。敏感信息如 'AWS_ACCESS_KEY_ID' 和 'AWS_SECRET_ACCESS_KEY' 请妥善保管。

基本使用方法

启动 Claude Desktop: 确保 Claude Desktop 客户端已启动并正确加载了配置文件。
在 Claude Desktop 中调用: 在 Claude Desktop 中，您可以使用 '@tool_code' 或其他方式调用 'iceberg' 服务器的 'execute_query' 工具，并提供 SQL 查询语句作为参数。

示例 (在 Claude Desktop 中可能的使用方式):

@tool_code iceberg.execute_query
{
  "query": "LIST TABLES"
}

或者查询特定表的数据：

@tool_code iceberg.execute_query
{
  "query": "SELECT * FROM my_table LIMIT 10"
}

Claude Desktop 将会将 SQL 查询发送到 MCP Iceberg Catalog Service，服务器执行查询后会将结果返回给 Claude Desktop。

请注意: 具体的工具调用方式和界面操作请参考 Claude Desktop 的文档。

关键词