Apache Iceberg MCP server

IcebergMCP is a Model Context Protocol (MCP) server that allows you to interact with your Apache Iceberg™ Lakehouse using natural language through MCP clients like Claude or Cursor. This tool enables you to query and analyze your data without writing complex code.

Installation

Prerequisites

Before installing IcebergMCP, ensure you have:

• Apache Iceberg™ catalog managed in AWS Glue
• AWS profile configured on your machine with access to the catalog
• uv package manager installed

To install the uv package manager:

brew install uv

Or follow the official installation guide.

Setting Up in Claude

1. In Claude, navigate to Settings > Developer > Edit Config > claude_desktop_config.json
2. Add the following configuration:

{
  "mcpServers": {
    "iceberg-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "iceberg-mcp",
        "iceberg-mcp"
      ],
      "env": {
        "ICEBERG_MCP_PROFILE": "<aws-profile-name>"
      }
    }
  }
}

Note: If uv cannot be found, replace with the full absolute path to the uv executable.

Setting Up in Cursor

1. In Cursor, go to Settings -> Cursor Settings -> MCP -> Add new global MCP server
2. Add the same configuration as shown above for Claude.

Configuration Options

You can configure the AWS connection using these environment variables:

• ICEBERG_MCP_PROFILE - AWS profile name to use (defaults to the default AWS profile if not specified)
• ICEBERG_MCP_REGION - AWS region to use (defaults to us-east-1)

Available Tools

IcebergMCP provides several tools for interacting with your Apache Iceberg™ tables:

• get_namespaces: Lists all namespaces in the Apache Iceberg™ catalog
• get_iceberg_tables: Retrieves all tables for a given namespace
• get_table_schema: Returns the schema for a specific table
• get_table_properties: Displays table properties like total size and record count
• get_table_partitions: Lists all partitions for a given table

Usage Examples

Here are some examples of natural language queries you can use with IcebergMCP:

• "List all namespaces in my catalog"
• "List all tables in 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

• All tools are currently read-only and cannot modify or delete data
• Currently only supports AWS Glue catalogs (Apache Iceberg™ REST Catalog support coming soon)

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.