buun-stack/trino/MCP.md

Claude Code Integration (MCP)

Claude Code can query Trino directly using the mcp-trino MCP server.

Installation

1. Install mcp-trino

brew install tuannvm/mcp/mcp-trino

2. Add to Claude Code Global Configuration

claude mcp add --scope user mcp-trino mcp-trino

This creates a global MCP server configuration at ~/.claude.json. The env: {} configuration means environment variables will be inherited from the parent process.

Basic Configuration

1. Create .env.claude

Create .env.claude with Trino connection settings:

# Trino Connection (Password Authentication)
TRINO_HOST=trino.yourdomain.com
TRINO_PORT=443
TRINO_SCHEME=https
TRINO_SSL=true
TRINO_SSL_INSECURE=true
TRINO_USER=admin
TRINO_PASSWORD="your-password-here"  # Direct password
TRINO_CATALOG=iceberg
TRINO_SCHEMA=default

# Performance: Limit schemas to improve query performance
TRINO_ALLOWED_CATALOGS=iceberg,tpch,postgresql
TRINO_ALLOWED_SCHEMAS=iceberg.ecommerce_marts,iceberg.analytics,tpch.sf1

# Query Configuration
TRINO_ALLOW_WRITE_QUERIES=false
TRINO_QUERY_TIMEOUT=30s

# MCP Transport (STDIO mode)
MCP_TRANSPORT=stdio

# OAuth (disabled for Trino connection - using password auth instead)
OAUTH_ENABLED=false

Get the admin password:

just trino::admin-password

2. Start Claude Code

Load environment variables and start Claude Code:

source .env.claude && claude

1Password Integration

For better security, store credentials in 1Password and inject them at runtime.

1. Create ~/.env.claude

Create ~/.env.claude in your home directory with 1Password references:

# Trino Connection (Password Authentication)
TRINO_HOST=trino.yourdomain.com
TRINO_PORT=443
TRINO_SCHEME=https
TRINO_SSL=true
TRINO_SSL_INSECURE=true
TRINO_USER=admin
TRINO_PASSWORD="op://Personal/trino/password"  # 1Password reference
TRINO_CATALOG=iceberg
TRINO_SCHEMA=default

# Performance: Limit schemas to improve query performance
TRINO_ALLOWED_CATALOGS=iceberg,tpch,postgresql
TRINO_ALLOWED_SCHEMAS=iceberg.ecommerce_marts,iceberg.analytics,tpch.sf1

# Query Configuration
TRINO_ALLOW_WRITE_QUERIES=false
TRINO_QUERY_TIMEOUT=30s

# MCP Transport (STDIO mode)
MCP_TRANSPORT=stdio

# OAuth (disabled for Trino connection - using password auth instead)
OAUTH_ENABLED=false

2. Create Shell Script

Create a shell script to inject secrets and start Claude Code (e.g., ~/bin/claude-op):

#!/usr/bin/env bash
set -euo pipefail
set -a
eval "$(op inject -i ~/.env.claude)"
set +a
claude

Make it executable:

chmod +x ~/bin/claude-op

3. Start Claude Code

claude-op

This command:

1. Injects secrets from 1Password using op inject
2. Exports environment variables to the shell
3. Starts Claude Code with environment variables inherited by mcp-trino

Usage

Once configured, Claude Code can interact with Trino using natural language:

Examples:

Show me all tables in the ecommerce_marts schema

What's the schema of the dim_products table?

Query the top 10 products by revenue

Available MCP Tools

The mcp-trino server provides the following tools:

• list_catalogs: List all available Trino catalogs
• list_schemas: List schemas in a catalog
• list_tables: List tables in a schema
• get_table_schema: Get column definitions and types for a table
• execute_query: Execute SELECT queries
• explain_query: Show query execution plan

Configuration Options

Performance Tuning

TRINO_ALLOWED_CATALOGS and TRINO_ALLOWED_SCHEMAS:

• Limits which catalogs and schemas are accessible
• Improves performance by reducing metadata queries
• Reduces attack surface

TRINO_QUERY_TIMEOUT:

• Maximum time allowed for query execution
• Prevents long-running queries from consuming resources

Security Settings

TRINO_ALLOW_WRITE_QUERIES:

• Set to false to prevent INSERT, UPDATE, DELETE, CREATE, DROP statements
• Recommended for read-only data exploration

TRINO_SSL_INSECURE:

• Set to true to allow self-signed certificates
• Required for development environments with self-signed certs
• Should be false in production with valid certificates

Troubleshooting

MCP Server Not Connecting

Check the MCP server status:

claude mcp list

You should see:

mcp-trino: mcp-trino - ✓ Connected

If it shows ✗ Failed to connect, check:

1. Environment variables are set: Verify .env.claude exists and contains all required variables
2. Trino is accessible: Test with curl -k https://${TRINO_HOST}
3. 1Password CLI is authenticated (if using 1Password): Run op whoami to check

Authentication Fails

If queries fail with authentication errors:

1. Verify password: Get the correct password with just trino::admin-password

2. Check environment variable: Ensure TRINO_PASSWORD is set correctly

3. Test manually:

   source .env.claude
   echo $TRINO_PASSWORD  # Verify password is loaded
   

For 1Password users:

source <(op inject -i ~/.env.claude)
echo $TRINO_PASSWORD  # Verify password injection worked

Architecture

Basic Configuration

User
  ↓
source .env.claude && claude
  ↓ (loads environment variables)
Claude Code (inherits env vars)
  ↓ (STDIO transport)
mcp-trino (reads env vars)
  ↓ (HTTPS with password auth)
Trino Server

Advanced: 1Password Integration

User
  ↓
claude-op (shell script)
  ↓ (op inject from ~/.env.claude)
Claude Code (inherits env vars)
  ↓ (STDIO transport)
mcp-trino (reads env vars)
  ↓ (HTTPS with password auth)
Trino Server

Key Points:

• mcp-trino runs as a child process of Claude Code
• Environment variables flow from shell → Claude Code → mcp-trino
• No configuration file needed for mcp-trino; all settings via environment variables
• 1Password injection happens once at startup (Advanced), not per-query

References

• mcp-trino GitHub Repository
• Claude Code MCP Documentation
• Model Context Protocol (MCP)
• 1Password CLI Documentation