Iceberg MCP

IcebergMCP 是一个 Model Context Protocol（MCP）服务，让你可以在 Claude、Cursor 或任何其他 MCP 客户端中使用自然语言与 Apache Iceberg™ 湖仓交互。

目录

• 安装
  • 先决条件
  • Claude
  • Cursor
• 配置
• 可用工具
• 示例
• 限制与安全注意事项
• 参与贡献

安装

先决条件

• 在 AWS Glue 中管理的 Apache Iceberg™ 目录
• 已在本机配置 AWS 配置文件，并拥有访问该目录的权限
• uv 包管理器——通过 brew install uv 安装，或参阅官方安装指南

Claude

1. 在 Claude 中，前往 Settings > Developer > Edit Config > claude_desktop_config.json

2. 添加以下内容：

{
  "mcpServers": {
    "iceberg-mcp": {
      "command": "uv", // If uv can't be found, replace with full absolute path to uv
      "args": [
        "run",
        "--with",
        "iceberg-mcp",
        "iceberg-mcp"
      ],
      "env": {
        "ICEBERG_MCP_PROFILE": "<aws-profile-name>"
      }
    }
  }
}

Cursor

1. 在 Cursor 中，前往 Settings -> Cursor Settings -> MCP -> Add new global MCP server

2. 添加以下内容：

{
  "mcpServers": {
    "iceberg-mcp": {
      "command": "uv", // If uv can't be found, replace with full absolute path to uv
      "args": [
        "run",
        "--with",
        "iceberg-mcp",
        "iceberg-mcp"
      ],
      "env": {
        "ICEBERG_MCP_PROFILE": "<aws-profile-name>"
      }
    }
  }
}

配置

可以使用环境变量配置 AWS 连接：

• ICEBERG_MCP_PROFILE - 要使用的 AWS 配置文件名称。此角色将被代入，并用于连接目录和对象存储。若未指定，则使用默认角色。
• ICEBERG_MCP_REGION - 要使用的 AWS 区域。此变量用于确定目录和对象存储的位置。默认值为 us-east-1。

可用工具

该服务提供以下工具，用于与 Apache Iceberg™ 表交互：

• get_namespaces：获取 Apache Iceberg™ 目录中的所有命名空间
• get_iceberg_tables：获取指定命名空间中的所有表
• get_table_schema：返回指定表的架构
• get_table_properties：返回指定表的属性，例如总大小和记录数
• get_table_partitions：获取指定表的所有分区

示例

安装并配置后，你就可以通过 MCP 客户端与 Apache Iceberg™ 表交互。以下是一些与湖仓交互的简单示例：

1. “列出目录中的所有命名空间”
2. “列出名为 bronze 的命名空间中的所有表”
3. “表 raw_events 中有哪些字符串列？”
4. “raw_events 表有多大？”
5. “生成一条 SQL 查询，计算 raw_metrics 中所有数值列的总和和 p95，筛选条件为 users_info 中的所有 VIP 用户”
6. “为什么最近查询 raw_events 的速度变慢了很多？”

限制与安全注意事项

• 目前所有工具均为只读，无法修改或删除湖仓中的数据
• 当前支持的目录：
  • AWS Glue
  • Apache Iceberg™ REST Catalog（即将推出！）

参与贡献

欢迎贡献！请随时提交 Pull Request。