Iceberg

IcebergMCP is an MCP server that lets you interact with your Apache Iceberg Lakehouse using natural language in MCP clients. It exposes read-only tools to query namespaces, tables, schemas, partitions, and table properties, enabling conversational data exploration without direct SQL. This guide shows you how to install, configure, and use IcebergMCP with your MCP client.

How to use

Once IcebergMCP is installed and running, connect to it from your MCP client (such as Claude or Cursor) and start asking questions about your Iceberg catalog. You can list namespaces, inspect table schemas, view table properties, fetch partitions, and generate queries to summarize numeric data. Examples of practical interactions include asking for all namespaces, listing tables in a namespace, examining a table’s schema, checking a table’s size, and exploring column types and statistics.

How to install

Prerequisites you need to satisfy before installing IcebergMCP:

• Apache Iceberg catalog managed in AWS Glue
• AWS profile configured on the machine with access to the catalog
• uv package manager installed on your system (install via brew install uv on macOS or follow the official guide)

# Install the UV tool if not already installed
brew install uv

# Start IcebergMCP using UV with the configured AWS profile
# Replace <aws-profile-name> with your actual AWS profile name
ICEBERG_MCP_PROFILE=<aws-profile-name> uv run --with iceberg-mcp iceberg-mcp

Additional content

Configuration, security, and usage notes are below to help you run IcebergMCP smoothly and securely.

Configuration

IcebergMCP can be configured via environment variables to control AWS access and region. The following variables are used to connect to your catalog and object storage:

• ICEBERG_MCP_PROFILE: The AWS profile name to assume for access to the catalog and storage. If not provided, the default role is used. Example: YOUR_AWS_PROFILE
• ICEBERG_MCP_REGION: The AWS region for the catalog and storage. If not specified, us-east-1 is used by default.

Examples

Here are representative tasks you can perform with IcebergMCP once it is running:

"List all namespaces in my catalog"; "List all tables for the namespace called bronze"; "What are all the string columns in the table raw_events?"; "What is the size of the raw_events table?"; "Generate an SQL query that calculates the sum and the p95 of all number columns in raw_metrics for all VIP users from users_info"; "Why did the queries on raw_events recently become much slower?"

Limitations & Security Considerations

All tools provided are read-only and cannot modify or delete data from your lakehouse. IcebergMCP currently supports AWS Glue catalogs; an Iceberg REST Catalog is planned for future release.

Contributing

Contributions are welcome. If you have improvements or bug fixes, you can submit a patch or feature request following standard collaboration practices for MCP projects.

Available tools

get_namespaces

Fetches all namespaces in the Apache Iceberg catalog.

get_iceberg_tables

Retrieves all tables within a specified namespace.

get_table_schema

Returns the schema for a given table.

get_table_properties

Returns properties for a given table, including total size and record count.

get_table_partitions

Retrieves all partitions for a given table.