trino-mcp 0.1.4

A simple Model Context Protocol (MCP) server for Trino with OAuth support

Trino MCP Server

A simple Model Context Protocol (MCP) server for Trino query engine with OAuth and Azure Service Principal (SPN) support.

Quick Start (TLDR)

Using with VS Code? Add to .vscode/mcp.json:

{
  "servers": {
    "trino": {
      "command": "uvx",
      "args": ["trino-mcp"],
      "env": {
        "TRINO_HOST": "${trino_host_address}",
        "TRINO_USER": "${env:USER}",
        "AUTH_METHOD": "OAuth2"
        // "ALLOW_WRITE_QUERIES": "true"  // Enable write operations (disabled by default)
      }
    }
  }
}

Want to run standalone?

# Set your Trino connection
export TRINO_HOST=localhost
export TRINO_PORT=8080
export TRINO_USER=trino

# Run directly (no installation needed)
uvx trino-mcp

That's it! The server will connect to your Trino cluster and provide query capabilities.

---

Features

• Core Trino Operations: Query catalogs, schemas, tables, and execute SQL
• Multiple Auth Methods: OAuth2, Azure Service Principal (SPN), basic username/password, or no auth
• Azure SPN with Auto-Refresh: Tokens are automatically refreshed before each request — no expiry issues for long-running servers
• Simple & Focused: Core Trino features without over-complication
• uvx Compatible: Run directly with uvx without installation
• Write Protection: Separate tools (execute_query and execute_query_read_only) with ALLOW_WRITE_QUERIES configuration to prevent accidental database modifications
• Query Watermarking: Automatically adds watermark comments to queries for tracking and auditing (includes username and version)

Prerequisites

• Python 3.10 or higher
• A running Trino server
• (Optional) Trino credentials for authentication
• (Optional) uvx

Setup & Configuration

General recommendation: using uvx or uv.

# From PyPI
uv pip install trino-mcp

# From PyPI
uvx trino-mcp

# Clone to local directory and install
uv pip install .
trino-mcp

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "trino": {
      "command": "uvx",
      "args": ["trino-mcp"],
      "env": {
        "TRINO_HOST": "localhost",
        "TRINO_PORT": "8080",
        "TRINO_USER": "trino"
        // "ALLOW_WRITE_QUERIES": "true"  // Enable write operations if needed
      }
    }
  }
}

Using with VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "trino": {
      "command": "uvx",
      "args": ["trino-mcp"],
      "env": {
        "TRINO_HOST": "${trino_host_address}",
        "TRINO_USER": "${env:USER}",
        "AUTH_METHOD": "OAuth2"
        // "ALLOW_WRITE_QUERIES": "true"  // Enable write operations if needed
      }
    }
  }
}

Environment Variables

Configure the server using environment variables or a .env file:

# Required
TRINO_HOST=localhost              # Your Trino server hostname
TRINO_PORT=8080                   # Trino server port (auto-set to 443 for Azure SPN/OAuth2)
TRINO_USER=trino                  # Username (auto-detected from JWT for Azure SPN)
TRINO_HTTP_SCHEME=http            # http or https (auto-set to https for Azure SPN/OAuth2)

# Optional
TRINO_CATALOG=my_catalog          # Default catalog
TRINO_SCHEMA=my_schema            # Default schema

# Authentication method: PASSWORD (default), OAUTH2, AZURE_SPN, or NONE
AUTH_METHOD=PASSWORD

# Option 1: Basic Authentication (AUTH_METHOD=PASSWORD)
TRINO_PASSWORD=your_password

# Option 2: OAuth2 (AUTH_METHOD=OAUTH2)
# Uses Trino's built-in OAuth2 flow (browser-based)

# Option 3: Azure Service Principal (AUTH_METHOD=AZURE_SPN)
# See "Azure SPN Authentication" section below

# Option 4: No auth (AUTH_METHOD=NONE)

# Security
ALLOW_WRITE_QUERIES=true          # Enable write operations (INSERT, UPDATE, DELETE, etc.)
                                  # Disabled by default for safety

Available Tools

The Trino MCP server provides the following tools. For the most up-to-date documentation, see the CI-generated tool documentation (available as artifacts in CI runs).

Quick summary:

• list_catalogs - List all available Trino catalogs
• list_schemas - List all schemas in a catalog
• list_tables - List all tables in a schema
• describe_table - Describe the structure of a table
• execute_query_read_only - Execute read-only SQL queries (SELECT, SHOW, DESCRIBE, EXPLAIN)
• execute_query - Execute any SQL query (requires ALLOW_WRITE_QUERIES=true for write operations)
• show_create_table - Show the CREATE TABLE statement for a table
• get_table_stats - Get statistics for a table

To generate the detailed tool documentation locally:

python3 scripts/generate_tool_docs.py
# This creates TOOLS.md and tools.json with complete documentation

Authentication

OAuth2

Set AUTH_METHOD=OAUTH2. The Trino Python client handles the OAuth2 flow automatically through a browser-based redirect — no manual JWT handling required.

Azure Service Principal (SPN)

For non-interactive / CI environments using Azure AD. Install with Azure extras:

# pip
pip install trino-mcp[azure]

# uv
uv pip install trino-mcp[azure]

# uvx (auto-installs extras)
uvx --extra azure trino-mcp

The server tries three credential methods in order:

1. az login (AzureCliCredential) — Easiest for local dev. Just run az login --service-principal beforehand.
2. Environment variables (ClientSecretCredential) — Best for CI/CD. Set AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
3. DefaultAzureCredential — Fallback for managed identity, etc.

AZURE_SCOPE is always required (the Trino server's Azure AD app scope, e.g. api://<trino-app-id>/.default).

Option A: Using az login (local development)

# Login as the service principal
az login --service-principal \
    --username "$AZURE_CLIENT_ID" \
    --password "$AZURE_CLIENT_SECRET" \
    --tenant "$AZURE_TENANT_ID" \
    --allow-no-subscriptions

.env:

AUTH_METHOD=AZURE_SPN
AZURE_SCOPE=api://your-trino-app-id/.default
TRINO_HOST=trino.example.com
TRINO_CATALOG=hive
TRINO_SCHEMA=default

Option B: Using environment variables (CI/CD)

.env:

AUTH_METHOD=AZURE_SPN
AZURE_SCOPE=api://your-trino-app-id/.default
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id
TRINO_HOST=trino.example.com
TRINO_CATALOG=hive
TRINO_SCHEMA=default

VS Code MCP config for Azure SPN

{
  "servers": {
    "trino": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--extra", "azure", "trino-mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

The server reads from .env automatically — no need to duplicate env vars in mcp.json.

Token auto-refresh: The server automatically refreshes Azure tokens before each Trino request, so it works reliably for long-running sessions without expiry issues.

Architecture

trino-mcp/
├── src/
│   └── trino_mcp/
│       ├── __init__.py
│       ├── config.py      # Configuration management
│       ├── client.py      # Trino client wrapper
│       └── server.py      # MCP server implementation
├── pyproject.toml         # Project configuration
├── .env.example          # Example environment variables
└── README.md             # This file

Development

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests (when available)
pytest

# Format code
black src/

# Type checking
mypy src/

Publishing a New Version

See docs/dev.md for release instructions.

Known Issues

Pytest exits with code 137 (SIGKILL)

If tests hang or exit with code 137, there may be stuck trino-mcp or uv processes consuming resources. Try killing them:

# Check for stuck processes
ps aux | grep -E "trino-mcp|uvx" | grep -v grep

# Kill if found
pkill -f trino-mcp

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For issues and questions:

• Open an issue on GitHub
• Check Trino documentation: https://trino.io/docs/
• Check MCP documentation: https://modelcontextprotocol.io/