MCP Iceberg Catalog

A MCP (Model Context Protocol) server implementation for interacting with Apache Iceberg. This server provides a SQL interface for querying and managing Iceberg tables through Claude desktop.

Claude Desktop as your Iceberg Data Lake Catalog

Related MCP server: PostgreSQL Query MCP Server

How to Install in Claude Desktop

Installing via Smithery

To install MCP Iceberg Catalog for Claude Desktop automatically via Smithery:

1. Prerequisites

   • Python 3.10 or higher

   • UV package installer (recommended) or pip

   • Access to an Iceberg REST catalog and S3-compatible storage

2. How to install in Claude Desktop Add the following configuration to claude_desktop_config.json:

Design

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 through stdio

   • Manages server lifecycle and initialization

2. Query Processor

   • Parses SQL queries using sqlparse

   • Supports operations:

     • LIST TABLES

     • DESCRIBE TABLE

     • SELECT

     • INSERT

3. Iceberg Integration

   • Uses pyiceberg for table operations

   • Integrates with PyArrow for efficient data handling

   • Manages catalog connections and table operations

PyIceberg Integration

The server utilizes PyIceberg in several ways:

1. Catalog Management

   • Connects to REST catalogs

   • Manages table metadata

   • Handles namespace operations

2. Data Operations

   • Converts between PyIceberg and PyArrow types

   • Handles data insertion through PyArrow tables

   • Manages table schemas and field types

3. Query Execution

   • Translates SQL to PyIceberg operations

   • Handles data scanning and filtering

   • Manages result set conversion

Further Implementation Needed

1. Query Operations

   • Implement UPDATE operations

   • Add DELETE support

   • Support for CREATE TABLE with schema definition

   • Add ALTER TABLE operations

   • Implement table partitioning support

2. Data Types

   • Support for complex types (arrays, maps, structs)

   • Add timestamp with timezone handling

   • Support for decimal types

   • Add nested field support

3. Performance Improvements

   • Implement batch inserts

   • Add query optimization

   • Support for parallel scans

   • Add caching layer for frequently accessed data

4. Security Features

   • Add authentication mechanisms

   • Implement role-based access control

   • Add row-level security

   • Support for encrypted connections

5. Monitoring and Management

   • Add metrics collection

   • Implement query logging

   • Add performance monitoring

   • Support for table maintenance operations

6. Error Handling

   • Improve error messages

   • Add retry mechanisms for transient failures

   • Implement transaction support

   • Add data validation