Trino (formerly PrestoSQL) is a powerful distributed SQL query engine designed for fast analytics on large datasets.

Architecture

graph TB
    subgraph "AI Clients"
        CC[Claude Code]
        CD[Claude Desktop]
        CR[Cursor]
        WS[Windsurf]
        CW[ChatWise]
    end
    
    subgraph "Authentication (Optional)"
        OP[OAuth Provider<br/>Okta/Google/Azure AD]
        JWT[JWT Tokens]
    end
    
    subgraph "MCP Server (mcp-trino)"
        HTTP[HTTP Transport<br/>/mcp endpoint]
        STDIO[STDIO Transport]
        AUTH[OAuth Middleware]
        TOOLS[MCP Tools<br/>• execute_query<br/>• list_catalogs<br/>• list_schemas<br/>• list_tables<br/>• get_table_schema<br/>• explain_query]
    end
    
    subgraph "Data Layer"
        TRINO[Trino Cluster<br/>Distributed SQL Engine]
        CATALOGS[Data Sources<br/>• PostgreSQL<br/>• MySQL<br/>• S3/Hive<br/>• BigQuery<br/>• MongoDB]
    end
    
    %% Connections
    CC -.->|OAuth Flow| OP
    OP -.->|JWT Token| JWT
    
    CC -->|HTTP + JWT| HTTP
    CD -->|STDIO| STDIO
    CR -->|HTTP + JWT| HTTP
    WS -->|STDIO| STDIO
    CW -->|HTTP + JWT| HTTP
    
    HTTP --> AUTH
    AUTH -->|Validated| TOOLS
    STDIO --> TOOLS
    
    TOOLS -->|SQL Queries| TRINO
    TRINO --> CATALOGS
    
    %% Styling
    classDef client fill:#e1f5fe
    classDef auth fill:#f3e5f5
    classDef server fill:#e8f5e8
    classDef data fill:#fff3e0
    
    class CC,CD,CR,WS,CW client
    class OP,JWT auth
    class HTTP,STDIO,AUTH,TOOLS server
    class TRINO,CATALOGS data

Key Components:

• AI Clients: Various MCP-compatible applications
• Authentication: Optional OAuth 2.0 with OIDC providers
• MCP Server: Go-based server with dual transport support
• CLI Mode: Interactive SQL shell for direct Trino access (psql-like)
• Data Layer: Trino cluster connecting to multiple data sources

Features

• ✅ Dual Mode: Works as both MCP server AND interactive CLI
  • CLI Mode: psql-like interactive SQL shell for direct Trino access
  • MCP Mode: Full MCP server for AI assistant integration
• ✅ MCP server implementation in Go
• ✅ Trino SQL query execution through MCP tools
• ✅ Catalog, schema, and table discovery
• ✅ Docker container support
• ✅ Supports both STDIO and HTTP transports
• ✅ OAuth 2.1 authentication via oauth-mcp-proxy library
  • 4 Providers: HMAC, Okta, Google, Azure AD
  • Native mode: Client handles OAuth directly (zero server-side secrets)
  • Proxy mode: Server proxies OAuth flow for simple clients
  • Production-ready: Token caching, PKCE, defense-in-depth security
  • Reusable: OAuth library available for any Go MCP server
• ✅ StreamableHTTP support with JWT authentication (upgraded from SSE)
• ✅ Backward compatibility with SSE endpoints
• ✅ Compatible with Cursor, Claude Desktop, Windsurf, ChatWise, and any MCP-compatible clients.
• ✅ User Identity Tracking:
  • Query Attribution (automatic): Tags queries with OAuth user via X-Trino-Client-Tags/Info headers
  • User Impersonation (opt-in): Execute queries as OAuth user via X-Trino-User header

Installation & Quick Start

Install:

# Homebrew
brew install tuannvm/mcp/mcp-trino

# Or one-liner (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/tuannvm/mcp-trino/main/install.sh | bash

Run (Local Development):

export TRINO_HOST=localhost TRINO_USER=trino
mcp-trino

For production deployment with OAuth, see Deployment Guide and OAuth Architecture.

CLI Mode

mcp-trino can be used as an interactive CLI similar to psql or the Trino CLI:

# Interactive REPL mode
mcp-trino --interactive

# Execute a query directly
mcp-trino query "SELECT * FROM my_table LIMIT 10"

# List catalogs, schemas, tables
mcp-trino catalogs
mcp-trino schemas my_catalog
mcp-trino tables my_catalog my_schema

# Describe a table
mcp-trino describe my_catalog.my_schema.my_table

# Explain a query
mcp-trino explain "SELECT COUNT(*) FROM my_table"

# Output formats
mcp-trino --format json query "SELECT 1"
mcp-trino --format csv query "SELECT 1"
mcp-trino --format table query "SELECT 1"  # default

Built-in Help

Every command has structured, LLM-friendly help output:

# Main help with all commands, flags, examples, and environment variables
mcp-trino --help

# Per-subcommand help
mcp-trino query --help
mcp-trino describe --help

Help output follows Unix man-page conventions with sections: NAME, SYNOPSIS, DESCRIPTION, COMMANDS, FLAGS, EXAMPLES, ENVIRONMENT, and CONFIGURATION.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Runtime error (connection failed, query error, etc.) | | 2 | Usage error (unknown command, invalid flags, missing arguments) |

Named Profiles

mcp-trino supports named connection profiles for easy switching between Trino environments.

Configuration File — supports both YAML (~/.config/trino/config.yaml) and JSON (~/.config/trino/config.json):

# ~/.config/trino/config.yaml
current: prod

profiles:
  prod:
    host: trino.example.com
    port: 443
    user: prod_user
    password: prod_password
    catalog: hive
    schema: analytics
    ssl:
      enabled: true
      insecure: false

  dev:
    host: localhost
    port: 8080
    user: trino
    catalog: memory
    schema: default

  staging:
    host: staging-trino.example.com
    port: 443
    user: staging_user

output:
  format: table

Or equivalently in JSON:

{
  "current": "prod",
  "profiles": {
    "prod": {
      "host": "trino.example.com",
      "port": 443,
      "user": "prod_user",
      "catalog": "hive",
      "ssl": { "enabled": true }
    },
    "dev": {
      "host": "localhost",
      "port": 8080,
      "user": "trino"
    }
  },
  "output": { "format": "table" }
}

When both files exist, config.json takes precedence. New configs default to JSON.

Profile Management Commands:

# List all profiles
mcp-trino config profile list

# Set default profile
mcp-trino config profile use prod

# Show profile details
mcp-trino config profile show staging

# Use a specific profile (overrides config file)
mcp-trino --profile dev catalogs

Configuration Precedence (highest to lowest):

1. CLI flags (--host, --port, etc.)
2. --profile flag
3. TRINO_PROFILE environment variable
4. current field in config file
5. default profile fallback
6. Environment variables (TRINO_HOST, etc.)

Environment Variables (lowest priority - overridden by profiles and flags):

export TRINO_HOST=trino.example.com
export TRINO_PORT=443
export TRINO_USER=myuser
export TRINO_PASSWORD=mypass
export TRINO_CATALOG=hive
export TRINO_SCHEMA=analytics
export TRINO_SSL=true

Secret Management (recommended):

Secrets are loaded purely from environment variables. Use a secrets CLI to inject them via Unix piping at launch time — the app never touches your vault:

# 1Password CLI — resolves op:// references in an env file
op run --env-file=.env -- mcp-trino

# Or inline per-variable
TRINO_PASSWORD=$(op read 'op://Engineering/Trino/password') mcp-trino

See docs/secrets.md for 1Password, Vault, and Kubernetes patterns, and for security nuances (shell-history, process-list, and env-var leakage).

REPL Meta-Commands (in interactive mode):

• \help - Show help
• \quit, \exit, \q - Exit REPL
• \history - Show command history
• \catalogs - List all catalogs
• \schemas [catalog] - List schemas
• \tables [catalog schema] - List tables
• \describe <table> - Describe table
• \format <table|json|csv> - Change output format

Usage

Supported Clients: Claude Desktop, Claude Code, Cursor, Windsurf, ChatWise

Available Tools: execute_query, list_catalogs, list_schemas, list_tables, get_table_schema, explain_query

For client integration and tool documentation, see [Integration Gui