MCP Trino Server

The MCP Trino Server is a Model Context Protocol (MCP) server that provides seamless integration with Trino and Iceberg, enabling advanced data exploration, querying, and table maintenance capabilities through a standard interface.

Use Cases

Interactive data exploration and analysis in Trino
Automated Iceberg table maintenance and optimization
Building AI-powered tools that interact with Trino databases
Executing and managing SQL queries with proper result formatting

Prerequisites

A running Trino server (or Docker Compose for local development)
Python 3.12 or higher
Docker (optional, for containerized deployment)

Quick Start

1. Clone the Repository

git clone https://github.com/alaturqua/mcp-trino-python.git
cd mcp-trino-python

2. Create Environment File

Create a .env file in the root directory:

TRINO_HOST=localhost
TRINO_PORT=8080
TRINO_USER=trino
TRINO_CATALOG=tpch
TRINO_SCHEMA=tiny

3. Run Trino Locally (Optional)

docker-compose up -d trino

This starts a Trino server on localhost:8080 with sample TPC-H and TPC-DS data.

Installation

Installing via Smithery

To install MCP Trino Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @alaturqua/mcp-trino-python --client claude

Using uv (Recommended)

uv sync
uv run src/server.py

Using pip

pip install -e .
python src/server.py

Transport Modes

The server supports three transport modes:

Transport	Description	Use Case
`stdio`	Standard I/O (default)	VS Code, Claude Desktop, local MCP clients
`streamable-http`	HTTP with streaming	Remote access, web clients, Docker
`sse`	Server-Sent Events	Legacy HTTP transport

Running with Different Transports

# stdio (default) - for VS Code and Claude Desktop
python src/server.py

# Streamable HTTP - for remote/web access
python src/server.py --transport streamable-http --host 0.0.0.0 --port 8000

# SSE - legacy HTTP transport
python src/server.py --transport sse --host 0.0.0.0 --port 8000

Usage with VS Code

Add to your VS Code settings (Ctrl+Shift+P → Preferences: Open User Settings (JSON)):

{
  "mcp": {
    "servers": {
      "mcp-trino-python": {
        "command": "uv",
        "args": [
          "run",
          "--with",
          "mcp[cli]",
          "--with",
          "trino",
          "--with",
          "loguru",
          "mcp",
          "run",
          "/path/to/mcp-trino-python/src/server.py"
        ],
        "envFile": "/path/to/mcp-trino-python/.env"
      }
    }
  }
}

Or add to .vscode/mcp.json in your workspace (without the mcp wrapper key).

Usage with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "trino": {
      "command": "python",
      "args": ["./src/server.py"],
      "env": {
        "TRINO_HOST": "your-trino-host",
        "TRINO_PORT": "8080",
        "TRINO_USER": "trino"
      }
    }
  }
}

Docker Usage

Build the Image

docker build -t mcp-trino-python .

Run with stdio (for VS Code)

docker run -i --rm \
  -e TRINO_HOST=host.docker.internal \
  -e TRINO_PORT=8080 \
  -e TRINO_USER=trino \
  mcp-trino-python

Run with Streamable HTTP

docker run -p 8000:8000 \
  -e TRINO_HOST=host.docker.internal \
  -e TRINO_PORT=8080 \
  mcp-trino-python \
  --transport streamable-http --host 0.0.0.0 --port 8000

Docker Compose

# Start Trino + MCP server with Streamable HTTP
docker-compose up -d

# Start with SSE transport
docker-compose --profile sse up -d

# Run stdio for testing
docker-compose --profile stdio run --rm mcp-trino-stdio

VS Code with Docker

{
  "mcp": {
    "servers": {
      "mcp-trino-python": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "--network",
          "mcp-trino-python_trino-network",
          "-e",
          "TRINO_HOST=trino",
          "-e",
          "TRINO_PORT=8080",
          "-e",
          "TRINO_USER=trino",
          "mcp-trino-python"
        ]
      }
    }
  }
}

Configuration

Environment Variables

Variable	Description	Default
TRINO_HOST	Trino server hostname	localhost
TRINO_PORT	Trino server port	8080
TRINO_USER	Trino username	trino
TRINO_CATALOG	Default catalog	None
TRINO_SCHEMA	Default schema	None
TRINO_HTTP_SCHEME	HTTP scheme (http/https)	http
TRINO_PASSWORD	Trino password	None

Tools

Query and Exploration Tools

show_catalogs
- List all available catalogs
- No parameters required
show_schemas
- List all schemas in a catalog
- Parameters:
  - catalog: Catalog name (string, required)
show_tables
- List all tables in a schema
- Parameters:
  - catalog: Catalog name (string, required)
  - schema: Schema name (string, required)
describe_table
- Show detailed table structure and column information
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
execute_query
- Execute a SQL query and return formatted results
- Parameters:
  - query: SQL query to execute (string, required)
show_catalog_tree
- Show a hierarchical tree view of catalogs, schemas, and tables
- Returns a formatted tree structure with visual indicators
- No parameters required
show_create_table
- Show the CREATE TABLE statement for a table
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_create_view
- Show the CREATE VIEW statement for a view
- Parameters:
  - view: View name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_stats
- Show statistics for a table
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)

Iceberg Table Maintenance

optimize
- Optimize an Iceberg table by compacting small files
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
optimize_manifests
- Optimize manifest files for an Iceberg table
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
expire_snapshots
- Remove old snapshots from an Iceberg table
- Parameters:
  - table: Table name (string, required)
  - retention_threshold: Age threshold (e.g., "7d") (string, optional)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)

Iceberg Metadata Inspection

show_table_properties
- Show Iceberg table properties
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_table_history
- Show Iceberg table history/changelog
- Contains snapshot timing, lineage, and ancestry information
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_metadata_log_entries
- Show Iceberg table metadata log entries
- Contains metadata file locations and sequence information
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_snapshots
- Show Iceberg table snapshots
- Contains snapshot details including operations and manifest files
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_manifests
- Show Iceberg table manifests for current or all snapshots
- Contains manifest file details and data file statistics
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
  - all_snapshots: Include all snapshots (boolean, optional)
show_partitions
- Show Iceberg table partitions
- Contains partition statistics and file counts
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_files
- Show Iceberg table data files in current snapshot
- Contains detailed file metadata and column statistics
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
show_entries
- Show Iceberg table manifest entries for current or all snapshots
- Contains entry status and detailed file metrics
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)
  - all_snapshots: Include all snapshots (boolean, optional)
show_refs
- Show Iceberg table references (branches and tags)
- Contains reference configuration and snapshot mapping
- Parameters:
  - table: Table name (string, required)
  - catalog: Catalog name (string, optional)
  - schema: Schema name (string, optional)

Query History

show_query_history
- Get the history of executed queries
- Parameters:
  - limit: Maximum number of queries to return (number, optional)

License

This project is licensed under the Apache 2.0 License. Please refer to the LICENSE file for the full terms.