alaturqua/mcp-trino-python

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

1. A running Trino server (or Docker Compose for local development)
2. Python 3.12 or higher
3. 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:

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

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.