MCP Iceberg Catalog

MCP Iceberg Catalog

Apache Iceberg と連携するための MCP（Model Context Protocol）サーバー実装です。このサーバーは、Claude デスクトップを通じて Iceberg テーブルをクエリおよび管理するための SQL インターフェースを提供します。

Iceberg データレイクカタログとしての Claude Desktop

Claude Desktop へのインストール方法

Smithery 経由でのインストール

Smithery 経由で MCP Iceberg Catalog を Claude Desktop に自動インストールするには、次の手順に従います。

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

1. 前提条件

   • Python 3.10 以降
   • UV パッケージインストーラー（推奨）または pip
   • Iceberg REST カタログおよび S3 互換ストレージへのアクセス

2. Claude Desktop へのインストール方法 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 サーバーは、次の 3 つの主要コンポーネントで構成されています。

1. MCP プロトコルハンドラー

   • Claude との通信に Model Context Protocol を実装します
   • stdio 経由でリクエスト／レスポンスのサイクルを処理します
   • サーバーのライフサイクルと初期化を管理します

2. クエリプロセッサー

   • sqlparse を使用して SQL クエリを解析します
   • 次の操作をサポートします。
     • LIST TABLES
     • DESCRIBE TABLE
     • SELECT
     • INSERT

3. Iceberg 連携

   • テーブル操作に pyiceberg を使用します
   • 効率的なデータ処理のために PyArrow と連携します
   • カタログ接続とテーブル操作を管理します

PyIceberg との連携

サーバーでは、PyIceberg を次のように利用します。

1. カタログ管理

   • REST カタログに接続します
   • テーブルメタデータを管理します
   • 名前空間の操作を処理します

2. データ操作

   • PyIceberg 型と PyArrow 型を相互に変換します
   • PyArrow テーブルを通じたデータ挿入を処理します
   • テーブルスキーマとフィールド型を管理します

3. クエリ実行

   • SQL を PyIceberg 操作に変換します
   • データスキャンとフィルタリングを処理します
   • 結果セットの変換を管理します

今後必要な実装

1. クエリ操作

   • UPDATE 操作を実装
   • DELETE のサポートを追加
   • スキーマ定義を含む CREATE TABLE をサポート
   • ALTER TABLE 操作を追加
   • テーブルのパーティショニングを実装

2. データ型

   • 複合型（配列、マップ、構造体）をサポート
   • タイムゾーン付きタイムスタンプの処理を追加
   • 10 進数型をサポート
   • ネストされたフィールドのサポートを追加

3. パフォーマンスの改善

   • バッチ挿入を実装
   • クエリ最適化を追加
   • 並列スキャンをサポート
   • 頻繁にアクセスされるデータ向けのキャッシュ層を追加

4. セキュリティ機能

   • 認証メカニズムを追加
   • ロールベースのアクセス制御を実装
   • 行レベルセキュリティを追加
   • 暗号化接続をサポート

5. 監視と管理

   • メトリクス収集を追加
   • クエリロギングを実装
   • パフォーマンス監視を追加
   • テーブルのメンテナンス操作をサポート

6. エラー処理

   • エラーメッセージを改善
   • 一時的な障害に対する再試行メカニズムを追加
   • トランザクションサポートを実装
   • データ検証を追加