mcp-trino

A Model Context Protocol (MCP) server for Trino, enabling AI assistants like Claude to query and explore data warehouses.

This project provides both a standalone MCP server and a composable Go library. The standalone server serves as a reference implementation, demonstrating all extensibility features including middleware, query interceptors, and result transformers. Import the pkg/tools and pkg/extensions packages into your own MCP server to add Trino capabilities with full customization for authentication, tenant isolation, audit logging, and more.

Features

• SQL Query Execution: Execute queries with configurable limits and timeouts
• Execution Plans: Analyze query plans (logical, distributed, IO)
• Schema Discovery: List catalogs, schemas, and tables
• Table Inspection: Describe columns and sample data
• Composable Design: Import as a Go package to build custom MCP servers

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:

Mac Type	Chip	Download
MacBook Air/Pro (2020+), Mac Mini (2020+), iMac (2021+), Mac Studio	Apple M1, M2, M3, M4 (arm64)	mcp-trino_*_darwin_arm64.mcpb
MacBook Air/Pro (pre-2020), Mac Mini (pre-2020), iMac (pre-2021)	Intel (amd64)	mcp-trino_*_darwin_amd64.mcpb

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 architecture
curl -L https://github.com/txn2/mcp-trino/releases/latest/download/mcp-trino_$(uname -s)_$(uname -m).tar.gz | tar xz

# Add to Claude Code
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

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:

# Production
claude mcp add trino-prod \
  -e TRINO_HOST=trino.prod.example.com \
  -e TRINO_USER=prod_user \
  -- mcp-trino

# Staging
claude 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.com
export TRINO_USER=your_user
export TRINO_PASSWORD=your_password
mcp-trino

Tools

Tool	Description
trino_query	Execute SQL queries with limit/timeout control
trino_explain	Get execution plans (logical/distributed/io/validate)
trino_list_catalogs	List available catalogs
trino_list_schemas	List schemas in a catalog
trino_list_tables	List tables in a schema
trino_describe_table	Get table columns and sample data
trino_list_connections	List all configured server connections

Configuration

Environment Variable	Description	Default
TRINO_HOST	Trino server hostname	localhost
TRINO_PORT	Trino server port	443 (SSL) / 8080
TRINO_USER	Authentication username	(required)
TRINO_PASSWORD	Authentication password	(optional)
TRINO_CATALOG	Default catalog	memory
TRINO_SCHEMA	Default schema	default
TRINO_SSL	Enable HTTPS	true for remote hosts
TRINO_SSL_VERIFY	Verify SSL certificates	true
TRINO_TIMEOUT	Query timeout (seconds)	120
TRINO_SOURCE	Client identifier	mcp-trino
TRINO_ADDITIONAL_SERVERS	Additional servers (JSON)	(optional)

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.com
export TRINO_USER=admin
export TRINO_PASSWORD=secret
export 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.yaml
trino:
  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 overrides
cfg, err := extensions.LoadConfig("/etc/mcp-trino/config.yaml")

// Convert to individual configs
clientCfg := 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:

Environment Variable	Default	Description
MCP_TRINO_EXT_LOGGING	false	Structured JSON logging of tool calls
MCP_TRINO_EXT_METRICS	false	In-memory metrics collection
MCP_TRINO_EXT_READONLY	true	Block modification statements (INSERT, UPDATE, DELETE, etc.)
MCP_TRINO_EXT_QUERYLOG	false	Log all SQL queries for audit
MCP_TRINO_EXT_METADATA	false	Add execution metadata footer to results
MCP_TRINO_EXT_ERRORS	true	Add helpful hints to error messages

Using Extensions in Custom Servers

import (
    "github.com/txn2/mcp-trino/pkg/extensions"
    "github.com/txn2/mcp-trino/pkg/tools"
)

// Load extension config from environment
extCfg := extensions.FromEnv()

// Or configure programmatically
extCfg := extensions.Config{
    EnableLogging:   true,
    EnableReadOnly:  true,
    EnableErrorHelp: true,
}

// Build toolkit options from extensions
toolkitOpts := extensions.BuildToolkitOptions(extCfg)

// Create toolkit with extensions
toolkit := tools.NewToolkit(trinoClient, toolsCfg, toolkitOpts...)

Custom Middleware and Interceptors

You can create custom middleware, interceptors, and transformers:

// Custom middleware for authentication
authMiddleware := tools.MiddlewareFunc{
    BeforeFn: func(ctx context.Context, tc *tools.ToolContext) (context.Context, error) {
        // Validate user permissions
        return ctx, nil
    },
}

// Custom interceptor for tenant isolation
tenantInterceptor := tools.QueryInterceptorFunc(
    func(ctx context.Context, sql string, toolName tools.ToolName) (string, error) {
        // Add WHERE tenant_id = ? clause
        return sql, nil
    },
)

// Apply to toolkit
toolkit := 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 repository
git clone https://github.com/txn2/mcp-trino.git
cd mcp-trino

# Build
make build

# Run tests
make test

# Run linter
make lint

# Run all checks
make verify

# Run with a local Trino (e.g., via Docker)
make docker-trino
export TRINO_HOST=localhost
export TRINO_PORT=8080
export TRINO_USER=admin
export 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

Related Projects

• Model Context Protocol - The MCP specification
• Trino - Distributed SQL query engine
• Official Go MCP SDK - Go SDK for MCP

---

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