How ryft-io/iceberg-mcp works
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