trino-data-interface-adapter

Introduction

The Model Context Protocol (MCP) Trino Server provides a standardized interface for interacting with distributed SQL query engines like Trino, often coupled with the Iceberg table format. Data analysis depends heavily on rapid access to diverse datasets; this tool streamlines querying and crucial data management operations, moving analysis closer to scientific method application.

Setup

Installing via Smithery

To integrate the MCP Trino Adapter into your Claude Desktop environment using the Smithery package manager, execute the following command:

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

Running Trino Locally

The simplest method to initiate a local Trino instance involves utilizing the provided Docker Compose configuration file for development:

docker-compose up -d

Executing this command will launch the Trino server, accessible by default on port 8080. You can then proceed with configuring the MCP adapter service to connect to it.

Usage with VS Code

For immediate integration within your development workflow, add the subsequent configuration block to your VS Code user settings file. Access this file via Ctrl + Shift + P, then selecting Preferences: Open User Settings (JSON).

Alternatively, place this configuration in a dedicated file named .vscode/mcp.json within your current project workspace. This permits configuration sharing across team members.

Note that the top-level "mcp" key should be omitted when using the workspace-specific .vscode/mcp.json file.

{
  "mcp": {
    "servers": {
      "trino": {
        "command": "docker",
        "args": ["run", "--rm", "ghcr.io/alaturqua/mcp-trino-python:latest"],
        "env": {
          "TRINO_HOST": "${input:trino_host}",
          "TRINO_PORT": "${input:trino_port}",
          "TRINO_USER": "${input:trino_user}",
          "TRINO_PASSWORD": "${input:trino_password}",
          "TRINO_HTTP_SCHEME": "${input:trino_http_scheme}",
          "TRINO_CATALOG": "${input:trino_catalog}",
          "TRINO_SCHEMA": "${input:trino_schema}"
        }
      }
    }
  }
}

Usage with Claude Desktop

Incorporate the following settings structure into your Claude Desktop configuration file to enable the adapter:

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

Configuration

Environment Variables

Configuration settings for the connection are managed via specific environment variables. Below details the expected variables, their purposes, and default values:

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

These functions support standard interactive data exploration and retrieving structural definitions, central to exploratory data analysis (EDA):

• show_catalogs

• Reports all available data catalogs.

• Requires no input arguments.

• show_schemas

• Retrieves schemas residing within a specified catalog.

• Parameters:

  • catalog: The catalog identifier (string, mandatory).

• show_tables

• Lists all database tables within a given schema.

• Parameters:

  • catalog: The catalog identifier (string, mandatory).
  • schema: The schema identifier (string, mandatory).

• describe_table

• Displays detailed metadata about a specific table structure.

• Parameters:

  • table: The target table name (string, mandatory).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• execute_query

• Executes arbitrary SQL code against the connected Trino engine.

• Parameters:

  • query: The SQL statement to be processed (string, mandatory).

• show_catalog_tree

• Presents a unified, hierarchical view encompassing catalogs, schemas, and tables.

• Returns a tree structure visualized for clarity.

• Requires no input arguments.

• show_create_table

• Fetches the DDL statement needed to recreate a specified table.

• Parameters:

  • table: Table name (string, mandatory).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_create_view

• Retrieves the definition DDL for a specified view object.

• Parameters:

  • view: View name (string, mandatory).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_stats

• Fetches performance and data statistics associated with a table.
• Parameters:
  • table: Table name (string, mandatory).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

Iceberg Table Maintenance

These utilities specifically target optimization and lifecycle management for tables utilizing the Iceberg format:

• optimize

• Initiates a compaction process to merge smaller data files into larger ones.

• Parameters:

  • table: Target table identifier (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• optimize_manifests

• Performs optimization procedures specifically on the Iceberg manifest files.

• Parameters:

  • table: Target table identifier (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• expire_snapshots

• Deletes historical snapshot metadata based on a specified time duration.
• Parameters:
  • table: Target table identifier (string, required).
  • retention_threshold: Defines the age limit, like "7d" (string, optional).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

Iceberg Metadata Inspection

Tools dedicated to revealing the underlying metadata structure and history of Iceberg tables:

• show_table_properties

• Displays configuration settings defined directly on the Iceberg table.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_table_history

• Provides a chronological log detailing all changes to the table structure and data.

• This includes tracing lineage and prior versions.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_metadata_log_entries

• Lists sequential entries from the table's metadata log, showing file locations.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_snapshots

• Details all extant snapshots for the table, including associated manifest files.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_manifests

• Shows the component manifest files for the active or all snapshots.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).
  • all_snapshots: Flag to inspect all versions (boolean, optional).

• show_partitions

• Outputs statistics regarding how the table data is physically partitioned.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_files

• Lists the physical data files making up the current table snapshot.

• Includes metrics on file structure and column distribution.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

• show_entries

• Displays the detailed entries contained within the manifest files.

• Parameters:

  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).
  • all_snapshots: Flag to inspect all versions (boolean, optional).

• show_refs

• Shows active references, such as branches and tags, pointing to specific snapshots.

• Parameters:
  • table: Table name (string, required).
  • catalog: Catalog name (string, optional).
  • schema: Schema name (string, optional).

Query History

This function allows users to review past operations executed via the interface:

• show_query_history
• Retrieves a record of previously executed SQL commands.
• Parameters:
  • limit: Controls the maximum count of history records returned (number, optional).

Related Topics

• Distributed SQL Query Engines (e.g., Trino)
• Table Formats for Data Lakes (e.g., Iceberg)
• Exploratory Data Analysis (EDA)
• Data Governance and Auditing
• Predictive Modeling
• Business Intelligence Aggregation

Extra Details

The original functionality provided comprehensive tools for schema inspection, DDL retrieval, and deep Iceberg metadata validation. While marketing details were omitted, understanding Trino's architecture clarifies this tool's role; Trino acts as a federated query layer over various data sources. The Iceberg integration specifically enables time-travel capabilities and ensures ACID properties on data lake storage, essential for reliable, consistent data analysis workflows.

Conclusion

This adapter serves as a programmatic bridge, simplifying complex interactions with high-performance analytical systems like Trino and Iceberg. By automating maintenance and providing granular metadata access, it supports more effective, data-driven decision-making, aligning with the core goals of modern data analysis practices across all operational domains.

License

This software is distributed under the terms of the Apache 2.0 License. Refer to the LICENSE file for complete legal stipulations.