JinDaGe - mcp-iceberg-service MCP Details

article

README

🚀 MCP 冰山目录

一个 MCP（模型上下文协议）服务器实现，用于与 Apache Iceberg 交互。此服务器通过 Claude 桌面提供 SQL 接口，可对 Iceberg 表进行查询和管理，为数据操作带来便利。

🚀 快速开始

在 Claude 桌面上作为 Iceberg 数据湖目录的 MySQL

📦 安装指南

通过 Smithery 安装

要通过 Smithery 自动为 Claude 桌面安装 MCP Iceberg 目录，可执行以下命令：

npx -y @smithery/cli install @ahodroj/mcp-iceberg-service --client claude

先决条件

Python 3.10 或更高版本
UV 包安装程序（推荐）或 pip
能够访问 Iceberg REST 目录和 S3 兼容存储

在 Claude 桌面上的安装步骤

将以下配置添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "iceberg": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH_TO_/mcp-iceberg-service",
        "run",
        "mcp-server-iceberg"
      ],
      "env": {
        "ICEBERG_CATALOG_URI" : "http://localhost:8181",
        "ICEBERG_WAREHOUSE" : "YOUR ICEBERG WAREHOUSE NAME",
        "S3_ENDPOINT" : "OPTIONAL IF USING S3",
        "AWS_ACCESS_KEY_ID" : "YOUR S3 ACCESS KEY",
        "AWS_SECRET_ACCESS_KEY" : "YOUR S3 SECRET KEY"
      }
    }
  }
}

🔧 技术细节

架构

该 MCP 服务器基于三个主要组件构建：

MCP 协议处理程序
- 实现模型上下文协议与 Claude 的通信。
- 处理标准输入输出中的请求/响应周期。
- 管理服务器的生命周期和初始化。
查询处理器
- 使用 sqlparse 解析 SQL 查询。
- 支持的操作包括：列出表格、描述表格、选择、插入。
Iceberg 集成
- 使用 pyiceberg 进行表操作。
- 集成 PyArrow 实现高效数据处理。
- 管理目录连接和表操作。

PyIceberg 集成

服务器在以下几个方面利用了 PyIceberg：

目录管理
- 连接到 REST 目录。
- 管理元数据表。
- 处理命名空间操作。
数据操作
- 实现 PyIceberg 和 PyArrow 类型之间的数据转换。
- 处理通过 PyArrow 表进行的数据插入。
- 管理表架构和字段类型。
查询执行
- 将 SQL 转换为 PyIceberg 操作。
- 处理数据扫描和过滤。
- 管理结果集转换。

📚 后续计划

查询操作

[ ] 实现 UPDATE 操作
[ ] 添加 DELETE 支持
[ ] 支持使用架构定义创建表格
[ ] 添加 ALTER TABLE 操作
[ ] 实现分区表支持

数据类型

[ ] 支持复杂类型（数组、映射、结构）
[ ] 添加带时区的时间戳处理
[ ] 支持小数类型
[ ] 添加嵌套字段支持

性能改进

[ ] 实现批处理插入
[ ] 添加查询优化
[ ] 支持并行扫描
[ ] 添加频繁访问数据的缓存层

安全功能

[ ] 添加身份验证机制
[ ] 实现基于角色的访问控制
[ ] 添加行级安全性
[ ] 支持加密连接

监控和管理

[ ] 添加指标收集
[ ] 实施查询记录
[ ] 添加性能监控
[ ] 支持表维护操作

错误处理

[ ] 改进错误消息
[ ] 添加重试机制以处理瞬时故障
[ ] 实现事务支持
[ ] 添加数据验证

mcp-iceberg-service