# Iceberg MCP Server (via Trino)

This is an Iceberg MCP Server using Trino as the compute engine, adapted from the [Impala fork](https://github.com/dipankarmazumdar/iceberg-mcp-server) 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

```bash
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:

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

Table health check:

```bash
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

```bash
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`

```bash
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:

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

Run with the MCP Inspector:

```bash
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.

```json
{
  "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)

```json
{
  "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

```json
{
  "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](https://github.com/cloudera/iceberg-mcp-server). See `LICENSE` and `NOTICE.txt` for attribution.

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