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):

Variable	Description	Default
TRINO_HOST	Trino coordinator hostname	required
TRINO_PORT	Trino port	443
TRINO_USER	Username	required
TRINO_PASSWORD	Password (LDAP/basic auth)	required
TRINO_CATALOG	Iceberg catalog name	iceberg
TRINO_SCHEMA	Default schema	default
TRINO_USE_SSL	Use HTTPS	true
TRINO_SSL_VERIFY	SSL verification (true, false, or path to CA cert)	true
MCP_TRANSPORT	stdio (default), http, or sse	stdio

Trino vs Impala SQL differences (handled internally)

Feature	Impala	Trino (this server)
Metadata tables	db.table.snapshots	"catalog"."schema"."table$snapshots"
Time travel (version)	FOR SYSTEM_VERSION AS OF	FOR VERSION AS OF
Time travel (time)	FOR SYSTEM_TIME AS OF '...'	FOR TIMESTAMP AS OF TIMESTAMP '...'
History	DESCRIBE HISTORY	$history metadata table

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.