MCP Iceberg Service

🚀 MCP Iceberg Catalog

An MCP (Model Context Protocol) server implementation for interacting with Apache Iceberg. This server provides a SQL interface through the Claude desktop to query and manage Iceberg tables.

MySQL as an Iceberg Data Lake Catalog on Claude Desktop

🚀 Quick Start

📦 Installation

Install via Smithery

To automatically install the MCP Iceberg Catalog for the Claude desktop via Smithery:

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

Prerequisites:

• Python 3.10 or higher
• UV package installer (recommended) or pip
• Access to an Iceberg REST catalog and S3-compatible storage

Manual Installation on Claude Desktop

Add the following configuration to 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"
      }
    }
  }
}

🔧 Technical Details

Architecture

The MCP server is built on three main components:

1. MCP Protocol Handler

   • Implements the Model Context Protocol for communication with Claude.
   • Handles request/response cycles in standard input/output.
   • Manages the server lifecycle and initialization.

2. Query Processor

   • Parses SQL queries using sqlparse.
   • Supported operations:
     • List tables
     • Describe tables
     • Select
     • Insert

3. Iceberg Integration

   • Performs table operations using pyiceberg.
   • Integrates PyArrow for efficient data processing.
   • Manages catalog connections and table operations.

PyIceberg Integration

The server leverages PyIceberg in the following aspects:

1. Catalog Management

   • Connects to the REST catalog.
   • Manages metadata tables.
   • Handles namespace operations.

2. Data Operations

   • Converts data between PyIceberg and PyArrow types.
   • Handles data insertion through PyArrow tables.
   • Manages table schemas and field types.

3. Query Execution

   • Converts SQL to PyIceberg operations.
   • Handles data scanning and filtering.
   • Manages result set conversion.

Future Implementation Plan

Query Operations

• [ ] Implement UPDATE operations.
• [ ] Add DELETE support.
• [ ] Support table creation using schema definitions.
• [ ] Add ALTER TABLE operations.
• [ ] Implement partitioned table support.

Data Types

• [ ] Support complex types (arrays, maps, structs).
• [ ] Add timestamp-with-timezone handling.
• [ ] Support decimal types.
• [ ] Add nested field support.

Performance Improvements

• [ ] Implement batch inserts.
• [ ] Add query optimization.
• [ ] Support parallel scanning.
• [ ] Add a cache layer for frequently accessed data.

Security Features

• [ ] Add authentication mechanisms.
• [ ] Implement role-based access control.
• [ ] Add row-level security.
• [ ] Support encrypted connections.

Monitoring and Management

• [ ] Add metric collection.
• [ ] Implement query logging.
• [ ] Add performance monitoring.
• [ ] Support table maintenance operations.

Error Handling

• [ ] Improve error messages.
• [ ] Add a retry mechanism for transient failures.
• [ ] Implement transaction support.
• [ ] Add data validation.