Mcp Trino

[txn2/mcp-trino]

[GitHub license] [Go Reference] [Go Report Card] [codecov] [OpenSSF Scorecard] [SLSA 3]

mcp-trino.txn2.com | Installation | Library Docs

A Model Context Protocol (MCP) server for Trino, enabling AI assistants to query and explore data warehouses with optional semantic context from metadata catalogs.

AI assistants excel at querying data but lack organizational context: which tables are trustworthy, what metrics mean, and which columns contain sensitive data. mcp-trino bridges this gap by connecting Trino to AI assistants through the MCP protocol, with an optional semantic layer that surfaces business metadata alongside query results.

MCP Data Platform Ecosystem

mcp-trino is part of a broader suite of open-source MCP servers designed to work together as a composable data platform. Each component can run standalone or be combined to give AI assistants unified access to storage, query engines, and metadata catalogs.

• txn2/mcp-data-platform
• txn2/mcp-datahub
• txn2/mcp-s3

Core Capabilities

Composable Architecture

• Import as a Go library to build custom MCP servers
• Add authentication, tenant isolation, audit logging without forking
• Middleware and interceptor patterns for enterprise requirements

Semantic Context

• Surface business descriptions, ownership, and data quality from metadata catalogs
• Mark sensitive columns for AI assistants
• Connect to DataHub, static files, or build custom metadata providers

Multi-Cluster Connectivity

• Query multiple Trino servers from a single MCP installation
• Unified interface across production, staging, and development environments

Secure Defaults

• Read-only mode prevents accidental data modification
• Query limits and timeouts prevent runaway operations
• SLSA Level 3 provenance for supply chain security

Features

• Execute SQL Queries: Run queries with configurable row limits and timeouts
• Analyze Execution Plans: Inspect logical, distributed, and I/O query plans
• Discover Schema: Browse catalogs, schemas, and tables across clusters
• Describe Tables: View column definitions with optional data samples
• Enrich with Context: Surface business metadata, ownership, and data quality
• Compose Custom Servers: Import as a Go library with middleware and interceptors

Installation

Homebrew (macOS)

brew install txn2/tap/mcp-trino

Claude Desktop

Claude Desktop is the GUI application for chatting with Claude. Install the mcp-trino extension to enable Trino queries in your conversations.

Option 1: One-Click Install (Recommended)

Download the .mcpb bundle for your Mac from the releases page and double-click to install:

Tip: Not sure which chip you have? Click → "About This Mac". Look for "Chip" (Apple Silicon) or "Processor" (Intel).

Option 2: Manual Configuration

Add to your claude_desktop_config.json (find via Claude Desktop → Settings → Developer):

{  "mcpServers": {    "trino": {      "command": "/opt/homebrew/bin/mcp-trino",      "env": {        "TRINO_HOST": "trino.example.com",        "TRINO_USER": "your_user",        "TRINO_PASSWORD": "your_password",        "TRINO_CATALOG": "hive",        "TRINO_SCHEMA": "default"      }    }  }}

Claude Code CLI

Claude Code is the terminal-based coding assistant. Add mcp-trino as an MCP server:

# Install via Homebrew first (see above), then:claude mcp add trino \  -e TRINO_HOST=trino.example.com \  -e TRINO_USER=your_user \  -e TRINO_PASSWORD=your_password \  -e TRINO_CATALOG=hive \  -- mcp-trino

Or download and install manually:

# Download the latest release for your architecturecurl -L https://github.com/txn2/mcp-trino/releases/latest/download/mcp-trino_$(uname -s)_$(uname -m).tar.gz | tar xz
# Add to Claude Codeclaude mcp add trino \  -e TRINO_HOST=trino.example.com \  -e TRINO_USER=your_user \  -e TRINO_PASSWORD=your_password \  -e TRINO_CATALOG=hive \  -- ./mcp-trino

Docker

docker run --rm -i \  -e TRINO_HOST=trino.example.com \  -e TRINO_USER=your_user \  -e TRINO_PASSWORD=your_password \  ghcr.io/txn2/mcp-trino:latest

Go Install

go install github.com/txn2/mcp-trino/cmd/mcp-trino@latest

Download Binary

Download pre-built binaries from the releases page. All releases are signed with Cosign and include SLSA provenance.

As a Library

go get github.com/txn2/mcp-trino

Quick Start

Multiple Trino Servers

You can configure multiple Trino instances with different names:

# Productionclaude mcp add trino-prod \  -e TRINO_HOST=trino.prod.example.com \  -e TRINO_USER=prod_user \  -- mcp-trino
# Stagingclaude mcp add trino-staging \  -e TRINO_HOST=trino.staging.example.com \  -e TRINO_USER=staging_user \  -- mcp-trino

Standalone Server

export TRINO_HOST=trino.example.comexport TRINO_USER=your_userexport TRINO_PASSWORD=your_passwordmcp-trino

Tools

Semantic Layer

AI agents operate more reliably when they understand organizational context: not just table structures, but which datasets are production-ready, what business terms mean, and which columns require careful handling.

mcp-trino's semantic layer integrates with metadata catalogs to surface this context alongside query results:

Providers

See the Semantic Layer Documentation for configuration, caching, and custom provider development.

Configuration

Multi-Server Configuration

Connect to multiple Trino servers from a single installation. Configure your primary server with the standard environment variables, then add additional servers via JSON:

export TRINO_HOST=prod.trino.example.comexport TRINO_USER=adminexport TRINO_PASSWORD=secretexport TRINO_ADDITIONAL_SERVERS='{  "staging": {"host": "staging.trino.example.com"},  "dev": {"host": "localhost", "port": 8080, "ssl": false}}'

Additional servers inherit credentials and settings from the primary server unless overridden:

{  "staging": {    "host": "staging.trino.example.com",    "user": "staging_user",    "catalog": "iceberg"  },  "dev": {    "host": "localhost",    "port": 8080,    "ssl": false,    "user": "admin"  }}

Use the connection parameter in any tool to target a specific server:

"Query the staging server: SELECT * FROM users LIMIT 10"→ trino_query(sql="...", connection="staging")

Use trino_list_connections to discover available connections.

File-Based Configuration

For production deployments using Kubernetes ConfigMaps, Vault, or other secret management systems, mcp-trino supports file-based configuration:

# config.yamltrino:  host: trino.example.com  port: 443  user: ${TRINO_USER}           # Supports env var expansion  password: ${TRINO_PASSWORD}   # Secrets can come from env  catalog: hive  schema: default  ssl: true  timeout: 120s
toolkit:  default_limit: 1000  max_limit: 10000  default_timeout: 120s  max_timeout: 300s
extensions:  logging: true  readonly: true  errors: true

Load configuration in your custom server:

import "github.com/txn2/mcp-trino/pkg/extensions"
// Load from file with env var overridescfg, err := extensions.LoadConfig("/etc/mcp-trino/config.yaml")
// Convert to individual configsclientCfg := cfg.ClientConfig()toolsCfg := cfg.ToolsConfig()extCfg := cfg.ExtConfig()

Using as a Library

mcp-trino is designed to be composable. You can import its tools into your own MCP server:

package main
import (    "context"    "log"
    "github.com/modelcontextprotocol/go-sdk/mcp"    "github.com/txn2/mcp-trino/pkg/client"    "github.com/txn2/mcp-trino/pkg/tools")
func main() {    // Create your MCP server    server := mcp.NewServer(&mcp.Implementation{        Name:    "my-data-server",        Version: "1.0.0",    }, nil)
    // Create Trino client    trinoClient, err := client.New(client.Config{        Host:    "trino.example.com",        Port:    443,        User:    "service_user",        SSL:     true,        Catalog: "hive",        Schema:  "analytics",    })    if err != nil {        log.Fatal(err)    }    defer trinoClient.Close()
    // Add Trino tools to your server    toolkit := tools.NewToolkit(trinoClient, tools.Config{        DefaultLimit: 1000,        MaxLimit:     10000,    })    toolkit.RegisterAll(server)
    // Add your own custom tools here...    // mcp.AddTool(server, &mcp.Tool{...}, handler)
    // Run the server    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {        log.Fatal(err)    }}

Extensions

The standalone server includes optional extensions that can be enabled via environment variables:

Using Extensions in Custom Servers

import (    "github.com/txn2/mcp-trino/pkg/extensions"    "github.com/txn2/mcp-trino/pkg/tools")
// Load extension config from environmentextCfg := extensions.FromEnv()
// Or configure programmaticallyextCfg := extensions.Config{    EnableLogging:   true,    EnableReadOnly:  true,    EnableErrorHelp: true,}
// Build toolkit options from extensionstoolkitOpts := extensions.BuildToolkitOptions(extCfg)
// Create toolkit with extensionstoolkit := tools.NewToolkit(trinoClient, toolsCfg, toolkitOpts...)

Custom Middleware and Interceptors

You can create custom middleware, interceptors, and transformers:

// Custom middleware for authenticationauthMiddleware := tools.MiddlewareFunc{    BeforeFn: func(ctx context.Context, tc *tools.ToolContext) (context.Context, error) {        // Validate user permissions        return ctx, nil    },}
// Custom interceptor for tenant isolationtenantInterceptor := tools.QueryInterceptorFunc(    func(ctx context.Context, sql string, toolName tools.ToolName) (string, error) {        // Add WHERE tenant_id = ? clause        return sql, nil    },)
// Apply to toolkittoolkit := tools.NewToolkit(client, cfg,    tools.WithMiddleware(authMiddleware),    tools.WithQueryInterceptor(tenantInterceptor),)

Security Considerations

• Credentials: Store passwords in environment variables or secret managers
• Query Limits: Default 1000 rows, max 10000 to prevent data exfiltration
• Timeouts: Default 120s timeout prevents runaway queries
• Read-Only: ReadOnly interceptor enabled by default blocks modification statements
• Access Control: Configure Trino roles and catalog access for defense in depth

Development

# Clone the repositorygit clone https://github.com/txn2/mcp-trino.gitcd mcp-trino
# Buildmake build
# Run testsmake test
# Run lintermake lint
# Run all checksmake verify
# Run with a local Trino (e.g., via Docker)make docker-trinoexport TRINO_HOST=localhostexport TRINO_PORT=8080export TRINO_USER=adminexport TRINO_SSL=false./mcp-trino

Contributing

We welcome contributions for bug fixes, tests, and documentation. See CONTRIBUTING.md for guidelines.

License

Apache License 2.0

Open source by Craig Johnston, sponsored by Deasil Works, Inc.