<div align="center"> <!-- omit in toc --> <img src="assets/iceberg-logo.svg" alt="Iceberg Logo" />

IcebergMCP 🚀

<strong>基于AI的Lakehouse集成</strong>

</div>

IcebergMCP 是一个 Model Context Protocol (MCP) 服务器，它允许您使用自然语言在 Claude、Cursor 或任何其他 MCP 客户端中与您的 Apache Iceberg™ Lakehouse 进行交互。

<video src="https://github.com/user-attachments/assets/907180f3-27ad-401a-9fa0-f3178cd290de"></video>

<!-- omit in toc -->

目录

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

安装

先决条件

• 在 AWS Glue 中管理的 Apache Iceberg™ 目录
• 配置了访问目录权限的 AWS 配置文件
• uv 包管理器 - 通过 brew install uv 安装或参阅 官方安装指南

Claude

1. 在 Claude 中，进入 设置 > 开发者 > 编辑配置 > claude_desktop_config.json

2. 添加以下内容：

{
  "mcpServers": {
    "iceberg-mcp": {
      "command": "uv", // 如果找不到 uv，请替换为 uv 的完整绝对路径
      "args": [
        "run",
        "--with",
        "iceberg-mcp",
        "iceberg-mcp"
      ],
      "env": {
        "ICEBERG_MCP_PROFILE": "<aws-profile-name>"
      }
    }
  }
}

Cursor

1. 在 Cursor 中，进入 设置 -> Cursor 设置 -> MCP -> 添加新的全局 MCP 服务器

2. 添加以下内容：

{
  "mcpServers": {
    "iceberg-mcp": {
      "command": "uv", // 如果找不到 uv，请替换为 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 目录（即将推出！）

贡献

欢迎贡献！请随时提交拉取请求。