Iceberg MCP Server (via Trino)

This is an Iceberg MCP Server using Trino as the compute engine, adapted from the Impala fork with Iceberg table health tooling and Trino SQL dialect support.

Model Context Protocol server for read-only access to Iceberg tables through Cloudera Trino (CDW Trino Virtual Warehouse): schema discovery, SQL queries, metadata-based health checks, time travel, and performance analysis.

Repository: https://github.com/dipankarmazumdar/iceberg-mcp-server-trino

Requirements

• Python 3.13+
• A Trino endpoint with Iceberg tables (tested with Cloudera Data Warehouse Trino Virtual Warehouse)
• LDAP or basic auth credentials for Trino

Quick start

git clone https://github.com/dipankarmazumdar/iceberg-mcp-server-trino.git
cd iceberg-mcp-server-trino
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env   # edit with your Trino coordinator + credentials

Connectivity test:

python -c "from iceberg_mcp_server_trino.tools import trino_tools; print(trino_tools.get_schema())"

Table health check:

python -c "from iceberg_mcp_server_trino.tools import trino_tools; print(trino_tools.get_table_health('your_iceberg_table'))"

Tools

• execute_query(query: str): Run a read-only SQL query on Trino and return results as JSON.
• get_schema(): List tables in the configured catalog and schema.
• get_table_health(table: str): Summarize Iceberg table health from metadata tables (snapshots, history, files, partitions, manifests, metadata_log_entries). Pass table or catalog.schema.table.

Iceberg semantics

• list_metadata_tables(table): List available Iceberg metadata tables.
• describe_metadata_table(table, metadata_name): Schema of a metadata table.
• query_metadata_table(table, metadata_name, limit?, columns?): Bounded metadata query.
• list_snapshots(table, limit?): Snapshot timeline from metadata.
• describe_table_history(table): Snapshot history via $history metadata table.
• get_snapshot_summary(table, snapshot_id): Detail for one snapshot.
• list_refs(table): Branches and tags.
• query_at_snapshot(table, snapshot_id, limit?, columns?): Time travel by snapshot ID (FOR VERSION AS OF).
• query_at_timestamp(table, timestamp, limit?, columns?): Time travel by timestamp (FOR TIMESTAMP AS OF).
• diff_snapshots(table, snapshot_id_a, snapshot_id_b): Compare two snapshots.

Performance & cost awareness

• explain_query(query): Trino EXPLAIN plan for a read-only query.
• partition_pruning_check(query): Heuristic partition pruning assessment from EXPLAIN.
• table_scan_cost_hints(table): Scan cost signals from files/partitions metadata.
• hot_partitions(table, limit?): Top partitions by file/record count (skew detection).

Local development

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env   # then edit with your Trino settings

Cloudera CDW example .env

TRINO_HOST=coordinator-default-trino.example.cloudera.site
TRINO_PORT=443
TRINO_USER=your-username
TRINO_PASSWORD=your-password
TRINO_CATALOG=iceberg
TRINO_SCHEMA=airlines
TRINO_USE_SSL=true
TRINO_SSL_VERIFY=true
MCP_TRANSPORT=stdio

Quick connectivity test:

python -c "from iceberg_mcp_server_trino.tools import trino_tools; print(trino_tools.get_schema())"

Run with the MCP Inspector:

fastmcp dev inspector src/iceberg_mcp_server_trino/server.py:mcp --with-editable .

Configuration

Set these environment variables (via .env or MCP config env block):

Trino vs Impala SQL differences (handled internally)

Usage with Cursor

Copy mcp.json.example to .cursor/mcp.json and update paths and credentials.

{
  "mcpServers": {
    "iceberg-mcp-server-trino": {
      "command": "/path/to/iceberg-mcp-server-trino/.venv/bin/python",
      "args": [
        "/path/to/iceberg-mcp-server-trino/src/iceberg_mcp_server_trino/server.py"
      ]
    }
  }
}

Credentials can live in .env (loaded by the server) or in the env block. Enable the server under Cursor Settings → MCP, then restart the server after code changes.

Usage with Claude Desktop

Option 1: Install from GitHub (recommended)

{
  "mcpServers": {
    "iceberg-mcp-server-trino": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/dipankarmazumdar/iceberg-mcp-server-trino@main",
        "run-server"
      ],
      "env": {
        "TRINO_HOST": "coordinator-default-trino.example.com",
        "TRINO_PORT": "443",
        "TRINO_USER": "username",
        "TRINO_PASSWORD": "password",
        "TRINO_CATALOG": "iceberg",
        "TRINO_SCHEMA": "default"
      }
    }
  }
}

Option 2: Local installation

{
  "mcpServers": {
    "iceberg-mcp-server-trino": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/iceberg-mcp-server-trino",
        "run",
        "src/iceberg_mcp_server_trino/server.py"
      ],
      "env": {
        "TRINO_HOST": "coordinator-default-trino.example.com",
        "TRINO_PORT": "443",
        "TRINO_USER": "username",
        "TRINO_PASSWORD": "password",
        "TRINO_CATALOG": "iceberg",
        "TRINO_SCHEMA": "default"
      }
    }
  }
}

Security

All MCP tools are read-only. execute_query rejects non-read-only SQL prefixes. Use a Trino user with least-privilege access in production.

Based on cloudera/iceberg-mcp-server. See LICENSE and NOTICE.txt for attribution.

Copyright (c) 2025 Cloudera, Inc. All rights reserved.