iceberg-mcp

🚀 IcebergMCP 🚀

IcebergMCP 是一个基于 AI 的 Lakehouse 集成工具，它作为 模型上下文协议 (MCP) 服务器，能让用户通过自然语言与基于 Apache Iceberg™ 的 Lakehouse 进行交互，并且支持 Claude、Cursor 或其他任何 MCP 客户端。

🚀 快速开始

IcebergMCP 提供了便捷的方式让您与基于 Apache Iceberg™ 的 Lakehouse 交互，下面为您详细介绍安装、配置及使用方法。

📦 安装指南

先决条件

• 由 AWS Glue 管理的 Apache Iceberg™ 目录。
• 已配置 AWS 凭据文件，且该凭据有权限访问目录。
• 已安装 uv 包管理器，您可以使用 brew install uv 进行安装，也可参见 官方安装指南。

Claude

1. 在 Claude 中，进入 设置 > 开发人员 > 编辑配置 > claude_desktop_config.json。
2. 添加以下内容：

{
  "mcpServers": {
    "iceberg-mcp": {
      "command": "uv", // 如果找不到 uv，请用绝对路径替换，例如 /path/to/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，请用绝对路径替换，例如 /path/to/uv
      "args": [
        "run",
        "--with",
        "iceberg-mcp",
        "iceberg-mcp"
      ],
      "env": {
        "ICEBERG_MCP_PROFILE": "<aws-profile-name>"
      }
    }
  }
}

🔧 配置

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

• ICEBERG_MCP_PROFILE：要使用的 AWS 配置文件名。此角色将被假设并用于连接目录和对象存储，默认情况下使用默认角色。
• ICEBERG_MCP_CATALOG：支持的目录类型：
  • aws.glue
  • iceberg.rest（即将推出！）

✨ 主要特性

当前版本支持以下目录：

AWS Glue

from iceberg_mcp.client import IcebergMCPClient

client = IcebergMCPClient(profile_name="your-aws-profile", catalog_type="aws.glue")
# 或指定区域
client = IcebergMCPClient(profile_name="your-aws-profile", region_name="us-west-2", catalog_type="aws.glue")

Apache Iceberg REST Catalog（即将推出）

from iceberg_mcp.client import IcebergMCPClient

client = IcebergMCPClient(catalog_type="iceberg.rest", catalog_url="http://your-iceberg-rest-server:8080")

💻 使用示例

基础用法

查询表结构

response = client.get_table_schema("my-database", "my-table")
print(response)

获取分区信息

response = client.list_partitions("my-database", "my-table", max_parts=10)
print(response)

📚 详细文档

限制与安全考虑

• 当前支持的目录类型：
  • AWS Glue
  • Apache Iceberg™ REST Catalog（即将推出！）

贡献

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