使用说明

项目简介

IcebergMCP 是一个基于 Model Context Protocol (MCP) 的服务器，旨在连接大型语言模型 (LLM) 与 Apache Iceberg 数据湖。它允许用户通过自然语言在支持 MCP 协议的客户端（如 Claude 和 Cursor）中查询和探索 Iceberg 数据湖中的数据，无需编写复杂的代码或 SQL 查询。

主要功能点

数据湖连接: 连接到 AWS Glue 管理的 Apache Iceberg 数据湖。
元数据查询: 提供工具查询 Iceberg 数据湖的元数据，包括：
- 列出所有命名空间 (namespaces)。
- 列出指定命名空间下的所有表 (tables)。
- 获取表的 Schema 信息（字段名、类型等）。
- 获取表的属性信息（大小、记录数等）。
- 获取表的 partitions 信息。
MCP 协议支持: 作为一个 MCP 服务器，它能够与任何 MCP 客户端进行通信，并按照 MCP 协议处理请求和返回响应。
易于集成: 提供详细的配置说明，方便集成到 Claude 和 Cursor 等 LLM 客户端。
安全性: 目前所有工具均为只读操作，不会修改或删除数据湖中的数据。

安装步骤

环境准备:
- 确保已安装 'uv' 包管理器。如果没有安装，可以通过 'brew install uv' (macOS) 或参考 uv 官方安装指南进行安装。
- 确保已配置 AWS CLI 并且拥有访问 Iceberg catalog 的 AWS profile。

配置 MCP 客户端:

Claude:

打开 Claude 客户端，进入 "Settings" -> "Developer" -> "Edit Config" -> "claude_desktop_config.json"。
在 'claude_desktop_config.json' 文件中，添加如下 'mcpServers' 配置：

{
  "mcpServers": {
    "iceberg-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "iceberg-mcp",
        "iceberg-mcp"
      ],
      "env": {
        "ICEBERG_MCP_PROFILE": "<aws-profile-name>"  // 将 <aws-profile-name> 替换为您的 AWS profile 名称
      }
    }
  }
}

参数说明:
- 'server name': "iceberg-mcp" (服务器名称，客户端配置中引用)
- 'command': "uv" (启动命令，假设 uv 可执行文件在 PATH 环境变量中)
- 'args': 启动参数，'run --with iceberg-mcp iceberg-mcp' 使用 uv 运行 iceberg-mcp 项目
- 'env': 环境变量，'ICEBERG_MCP_PROFILE' 指定用于连接 AWS 的 profile 名称

Cursor:
- 打开 Cursor 客户端，进入 "Settings" -> "Cursor Settings" -> "MCP" -> "Add new global MCP server"。
- 在 MCP 服务器配置中，添加与 Claude 相同的 'mcpServers' 配置信息。

服务器配置

IcebergMCP 服务器通过以下环境变量进行配置：

'ICEBERG_MCP_PROFILE': AWS profile 名称，用于连接 AWS Glue catalog 和对象存储。如果未指定，则使用默认 profile。
'ICEBERG_AWS_REGION': AWS 区域，用于确定 catalog 和对象存储位置。默认为 'us-east-1'。

可以在 MCP 客户端的 'env' 配置中设置 'ICEBERG_MCP_PROFILE' 环境变量。'ICEBERG_AWS_REGION' 环境变量通常可以省略，除非你的 Iceberg catalog 不在 'us-east-1' 区域。

基本使用方法

配置完成后，在 Claude 或 Cursor 客户端中，可以直接使用自然语言与 Iceberg 数据湖进行交互。例如：

在聊天框中输入 "List all namespaces in my catalog" (列出我 catalog 中的所有命名空间)。
输入 "List all tables for the namespace called 'bronze'" (列出名为 'bronze' 的命名空间下的所有表)。
输入 "What are all the string columns in the table 'raw_events'?" (表 'raw_events' 中有哪些字符串类型的列？)。
输入 "What is the size of the 'raw_events' table?" (表 'raw_events' 的大小是多少？)。

客户端会将这些自然语言请求转换为对 IcebergMCP 服务器的工具调用，服务器执行相应的操作并返回结果给客户端。

关键词