# ahodroj/mcp-iceberg-service architecture

> Architecture diagram of the GitHub repository ahodroj/mcp-iceberg-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahodroj/mcp-iceberg-service
- Repository: https://github.com/ahodroj/mcp-iceberg-service

## Overview

##### Project type and purpose
- This is a standalone Python microservice (“MCP Iceberg Catalog”) that implements the Model Context Protocol to expose a SQL interface to Apache Iceberg data lakes.
- It is invoked by Claude Desktop over stdio (via the UV runner), parses SQL commands, executes them against an Iceberg catalog and S3-backed warehouse, then returns results.

##### File structure
- Top level:
- Dockerfile, pyproject.toml, requirements.txt, smithery.yaml – containerization and metadata
- src/mcp_server_iceberg/server.py – entry point
- __init__.py – package marker
- uv.lock – UV CLI lockfile
- Naming indicates a single-service Python package, no frontend.
- Deployment via UV (the “uv” CLI) and Docker.

##### README for architecture insights
- Three main logical components:
- MCP Protocol Handler (stdio, request/response)
- Query Processor (SQL parsing via sqlparse, command handling: LIST, DESCRIBE, SELECT, INSERT)
- Iceberg Integration (PyIceberg + PyArrow for metadata & data operations)
- External dependencies:
- Iceberg REST catalog (HTTP)
- S3-compatible storage for tables
- Claude Desktop as the client orchestrator

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Claude["Claude Desktop"]:::client

    %% Service Boundary
    subgraph "MCP Iceberg Catalog Service" 
        direction TB
        Env["Environment Variables\nICEBERG_CATALOG_URI, S3_Creds"]:::config
        Init["__init__.py"]:::internal
        Handler["MCP Protocol Handler\n(server.py)"]:::internal
        Query["Query Processor\n(sqlparse)"]:::internal
        Integration["Iceberg Integration\n(PyIceberg, PyArrow)"]:::internal
        Env --> Handler
        Init --> Handler
        Handler -->|"RPC calls"| Query
        Query -->|"method calls"| Integration
    end

    %% External Services
    IcebergREST["Apache Iceberg REST Catalog"]:::external
    S3["S3-Compatible Data Lake"]:::external

    %% Build & Metadata
    subgraph "Build & Config Files"
        direction TB
        Dockerfile["Dockerfile"]:::config
        PyProj["pyproject.toml"]:::config
        Req["requirements.txt"]:::config
        Smith["smithery.yaml"]:::config
        UVLock["uv.lock"]:::config
        Readme["README.md"]:::config
    end

    %% Connections
    Claude -->|"stdin/stdout (UV runner)"| Handler
    Integration -->|"HTTP REST"| IcebergREST
    Integration -->|"Read/Write Objects"| S3

    %% Click Events
    click Handler "https://github.com/ahodroj/mcp-iceberg-service/blob/main/src/mcp_server_iceberg/server.py"
    click Init "https://github.com/ahodroj/mcp-iceberg-service/blob/main/__init__.py"
    click Dockerfile "https://github.com/ahodroj/mcp-iceberg-service/tree/main/Dockerfile"
    click PyProj "https://github.com/ahodroj/mcp-iceberg-service/blob/main/pyproject.toml"
    click Req "https://github.com/ahodroj/mcp-iceberg-service/blob/main/requirements.txt"
    click Smith "https://github.com/ahodroj/mcp-iceberg-service/blob/main/smithery.yaml"
    click UVLock "https://github.com/ahodroj/mcp-iceberg-service/blob/main/uv.lock"
    click Readme "https://github.com/ahodroj/mcp-iceberg-service/blob/main/README.md"

    %% Styles
    classDef client fill:#f96,stroke:#333,stroke-width:1px
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#afa,stroke:#333,stroke-width:1px
    classDef config fill:#ddf,stroke:#333,stroke-width:1px
```
