Apache Iceberg

by ahodroj

3 stars

292 downloads

Not rated

GitHub

About

Provides a SQL interface for querying and managing Apache Iceberg tables through connections to Iceberg REST catalogs and S3-compatible storage, enabling data analysts to interact with data lakes without switching contexts.

Details

Author: ahodroj
Repository: ahodroj/mcp-iceberg-service
GitHub stars: 3
Downloads: 292
Categories: Database, Other, File Management, Developer Tools, Design, AI, Search, Infrastructure, Frontend, API

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Apache Iceberg

Command (node, npx, python, etc.) uv
Arguments
- Argument 1 --directory
- Argument 2 PATH_TO_/mcp-iceberg-service
- Argument 3 run
- Argument 4 mcp-server-iceberg
Environment
- S3_ENDPOINT OPTIONAL IF USING S3
- AWS_ACCESS_KEY_ID YOUR S3 ACCESS KEY
- ICEBERG_WAREHOUSE YOUR ICEBERG WAREHOUSE NAME
- ICEBERG_CATALOG_URI http://localhost:8181
- AWS_SECRET_ACCESS_KEY YOUR S3 SECRET KEY
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

From the repository

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

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

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:

{
  "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"
      }
    }
  }
}

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "apache iceberg": {
            "env": {
                "S3_ENDPOINT": "OPTIONAL IF USING S3",
                "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
                "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
                "ICEBERG_CATALOG_URI": "http://localhost:8181",
                "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
            },
            "args": [
                "--directory",
                "PATH_TO_/mcp-iceberg-service",
                "run",
                "mcp-server-iceberg"
            ],
            "command": "uv"
        }
    }
}

Linux

{
    "env": {
        "S3_ENDPOINT": "OPTIONAL IF USING S3",
        "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
        "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
        "ICEBERG_CATALOG_URI": "http://localhost:8181",
        "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
    },
    "args": [
        "--directory",
        "PATH_TO_/mcp-iceberg-service",
        "run",
        "mcp-server-iceberg"
    ],
    "command": "uv"
}

Macos

{
    "env": {
        "S3_ENDPOINT": "OPTIONAL IF USING S3",
        "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
        "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
        "ICEBERG_CATALOG_URI": "http://localhost:8181",
        "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
    },
    "args": [
        "--directory",
        "PATH_TO_/mcp-iceberg-service",
        "run",
        "mcp-server-iceberg"
    ],
    "command": "uv"
}

Windows

{
    "env": {
        "S3_ENDPOINT": "OPTIONAL IF USING S3",
        "AWS_ACCESS_KEY_ID": "YOUR S3 ACCESS KEY",
        "ICEBERG_WAREHOUSE": "YOUR ICEBERG WAREHOUSE NAME",
        "ICEBERG_CATALOG_URI": "http://localhost:8181",
        "AWS_SECRET_ACCESS_KEY": "YOUR S3 SECRET KEY"
    },
    "args": [
        "--directory",
        "PATH_TO_/mcp-iceberg-service",
        "run",
        "mcp-server-iceberg"
    ],
    "command": "uv"
}

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

How to Install in Claude Desktop

Installing via Smithery

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

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

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:

{
  "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"
      }
    }
  }
}

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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

Linux

Macos

Windows

MCP Iceberg Catalog

Claude Desktop as your Iceberg Data Lake Catalog

How to Install in Claude Desktop

Installing via Smithery

Design

Architecture

PyIceberg Integration

Further Implementation Needed

Install

More like this

Sequential Thinking

Redis

Filesystem

EverArt

Google Drive

Sqlite