# ryft-io/iceberg-mcp architecture

> Architecture diagram of the GitHub repository ryft-io/iceberg-mcp, 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/ryft-io/iceberg-mcp
- Repository: https://github.com/ryft-io/iceberg-mcp

## Overview

##### Project Type & Purpose
- IcebergMCP is an open-source, AI-native “Model Context Protocol” (MCP) server written in Python.
- It exposes a set of read-only tools (e.g. get_namespaces, get_iceberg_tables, get_table_schema, etc.) that let an MCP client (Claude, Cursor, etc.) talk in natural language to an Apache Iceberg™ Lakehouse in AWS (Glue catalog + underlying object store).

##### High-Level Architecture
Components:
a. MCP Client (Claude, Cursor, any MCP-capable UI)
b. MCP Server Process (“iceberg-mcp” entrypoint invoked by uv)
- Config Loader (iceberg_config.py)
- Server & Tool Registry (iceberg_server.py)
c. AWS Services
- AWS Glue Catalog (metadata store for Iceberg tables)
- S3 / Object Storage (Iceberg table files)
- AWS STS / IAM (assume-role via ICEBERG_MCP_PROFILE)

##### Interactions & Data Flow
1. User types NL query in MCP Client →
2. Client launches “uv run --with iceberg-mcp iceberg-mcp” (stdin/stdout bidirectional) →
3. iceberg_mcp.iceberg_server spins up, reads env vars (ICEBERG_MCP_PROFILE, ICEBERG_MCP_REGION) via iceberg_config →
4. Client issues MCP call (e.g. get_namespaces) →
5. Server handler invokes boto3 against AWS Glue →
6. Glue returns namespace list →
7. Server returns JSON over MCP protocol →
8. Client renders answer in the UI

##### Key Architectural Patterns & Principles
- Single-process, plugin-style server: tools are registered functions in iceberg_server.py
- Separation of concerns:
- Configuration & AWS session creation (iceberg_config.py)
- Protocol handling & tool dispatch (iceberg_server.py)
- External dependency isolation: AWS interactions via boto3, all read-only
- Extensibility: add new tool functions in iceberg_server.py or new modules

- Clear, self-explanatory labels on every component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Client["MCP Client<br/>(Claude, Cursor, etc.)"]:::client
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "iceberg-mcp Server"
            config["Config Loader<br/>iceberg_config.py"]:::module
            server["Tool Registry & Handler<br/>iceberg_server.py"]:::module
            env["Env Vars: ICEBERG_MCP_PROFILE,<br/>ICEBERG_MCP_REGION"]:::annotation
        end
        pkg["iceberg_mcp/ (Package Dir)"]:::module
    end

    %% Data Layer (AWS Cloud)
    subgraph "Data Layer (AWS Cloud)"
        sts["AWS STS / IAM"]:::aws
        glue["AWS Glue Catalog"]:::aws
        s3["S3 / Object Storage"]:::aws
    end

    %% Repository Files
    subgraph "Repository Files"
        toml["pyproject.toml"]:::file
        ci[".github/workflows/ci.yaml"]:::file
        lock["uv.lock"]:::file
        readme["README.md"]:::file
        license["LICENSE"]:::file
    end

    %% Connections
    Client -->|"MCP over STDIN/STDOUT"| server
    server -->|"AssumeRole"| sts
    server -->|"get_namespaces etc."| glue
    server -->|"Read manifests/files"| s3
    sts -->|"Credentials"| server
    glue -->|"Metadata"| server
    s3 -->|"Data"| server
    server -->|"JSON Response"| Client

    %% Click Events
    click config "https://github.com/ryft-io/iceberg-mcp/blob/main/iceberg_mcp/iceberg_config.py"
    click server "https://github.com/ryft-io/iceberg-mcp/blob/main/iceberg_mcp/iceberg_server.py"
    click pkg "https://github.com/ryft-io/iceberg-mcp/tree/main/iceberg_mcp/"
    click toml "https://github.com/ryft-io/iceberg-mcp/blob/main/pyproject.toml"
    click ci "https://github.com/ryft-io/iceberg-mcp/blob/main/.github/workflows/ci.yaml"
    click lock "https://github.com/ryft-io/iceberg-mcp/blob/main/uv.lock"
    click readme "https://github.com/ryft-io/iceberg-mcp/blob/main/README.md"
    click license "https://github.com/ryft-io/iceberg-mcp/tree/main/LICENSE"

    %% Styles
    classDef client fill:#ffa500,stroke:#333,stroke-width:1px
    classDef module fill:#add8e6,stroke:#333,stroke-width:1px
    classDef aws fill:#7cfc00,stroke:#333,stroke-width:1px
    classDef annotation fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef file fill:#d3d3d3,stroke:#333,stroke-width:1px
```
