MCP Trino

Trino MCP Server in Go

A high-performance Model Context Protocol (MCP) server for Trino implemented in Go. This project enables AI assistants to seamlessly interact with Trino's distributed SQL query engine through standardized MCP tools.

Overview

This project implements a Model Context Protocol (MCP) server for Trino in Go. It enables AI assistants to access Trino's distributed SQL query engine through standardized MCP tools.

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 Okta/Google/Azure AD] JWT[JWT Tokens] end

subgraph "MCP Server (mcp-trino)" HTTP[HTTP Transport /mcp endpoint] STDIO[STDIO Transport] AUTH[OAuth Middleware] TOOLS[MCP Tools • execute_query • list_catalogs • list_schemas • list_tables • get_table_schema • explain_query] end

subgraph "Data Layer" TRINO[Trino Cluster Distributed SQL Engine] CATALOGS[Data Sources • PostgreSQL • MySQL • S3/Hive • BigQuery • 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

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 - Describe table
• \format - 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 Guide and Tools Reference.

Configuration

Key Variables: TRINO_HOST, TRINO_USER, TRINO_SCHEME, MCP_TRANSPORT, OAUTH_PROVIDER

Secret Management: Inject secrets through the process environment — mcp-trino reads them directly. See docs/secrets.md for 1Password, Vault, and Kubernetes recipes.

# 1Password (biometric-gated, zero disk writes)

op run --env-file=.env -- mcp-trino

Vault (via vault-agent or CLI)

TRINO_PASSWORD=$(vault kv get -field=password secret/mcp-trino) mcp-trino

Kubernetes: use standard Secret → envFrom in the Helm chart values

OAuth Configuration:

# Native mode (most secure - zero server-side secrets)

export OAUTH_ENABLED=true OAUTH_MODE=native OAUTH_PROVIDER=okta export OIDC_ISSUER=https://company.okta.com OIDC_AUDIENCE=https://mcp-server.com

Proxy mode (centralized credential management)

export OAUTH_MODE=proxy OIDC_CLIENT_ID=app-id OIDC_CLIENT_SECRET=secret export OAUTH_REDIRECT_URI=https://mcp-server.com/oauth/callback # Fixed mode (localhost-only) export OAUTH_REDIRECT_URI=https://app1.com/cb,https://app2.com/cb # Allowlist mode export JWT_SECRET=$(openssl rand -hex 32) # Required for multi-pod deployments

Performance Optimization:

# Focus AI on specific schemas only (10-20x performance improvement)

export TRINO_ALLOWED_SCHEMAS="hive.analytics,hive.marts,hive.reporting"

User Identity Tracking:

# Query Attribution is AUTOMATIC when OAuth is enabled

Queries are tagged with X-Trino-Client-Tags and X-Trino-Client-Info headers

For full impersonation (Trino enforces user permissions):

export TRINO_ENABLE_IMPERSONATION=true export TRINO_IMPERSONATION_FIELD=email # Options: username, email, subject

For complete configuration, see Deployment Guide, OAuth Guide, Allowlists Guide, and User Identity Guide.

O