Trino MCP Server in Go

Go 版 Trino MCP 服务

一个使用 Go 实现的高性能 Trino 模型上下文协议（MCP）服务。该项目支持 AI 助手通过标准化的 MCP 工具，无缝访问 Trino 分布式 SQL 查询引擎。

概览

该项目使用 Go 实现了一个面向 Trino 的模型上下文协议（MCP）服务。它支持 AI 助手通过标准化的 MCP 工具访问 Trino 分布式 SQL 查询引擎。

Trino（前身为 PrestoSQL）是一款强大的分布式 SQL 查询引擎，专为大型数据集的快速分析而设计。

架构

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

主要组件：

• AI 客户端：各种兼容 MCP 的应用程序
• 身份验证：可选使用 OIDC 提供商的 OAuth 2.0
• MCP 服务：支持双传输方式的 Go 服务
• 命令行模式：用于直接访问 Trino 的交互式 SQL Shell（类似 psql）
• 数据层：连接多个数据源的 Trino 集群

功能

• ✅ 双模式：既可作为 MCP 服务，也可作为交互式命令行工具运行
  • 命令行模式：用于直接访问 Trino 的交互式 SQL Shell（类似 psql）
  • MCP 模式：用于集成 AI 助手的完整 MCP 服务
• ✅ 使用 Go 实现 MCP 服务
• ✅ 通过 MCP 工具执行 Trino SQL 查询
• ✅ 发现目录、模式和表
• ✅ 支持 Docker 容器
• ✅ 同时支持 STDIO 和 HTTP 传输
• ✅ 通过 oauth-mcp-proxy 库实现 OAuth 2.1 身份验证
  • 4 个提供商：HMAC、Okta、Google、Azure AD
  • 原生模式：客户端直接处理 OAuth（服务端无需密钥）
  • 代理模式：服务端代理 OAuth 流程，适用于简单客户端
  • 可用于生产环境：令牌缓存、PKCE、纵深防御安全机制
  • 可复用：OAuth 库也可用于任何 Go MCP 服务
• ✅ 支持带 JWT 身份验证的 StreamableHTTP（由 SSE 升级而来）
• ✅ 向后兼容 SSE 端点
• ✅ 兼容 Cursor、Claude Desktop、Windsurf、ChatWise 以及任何兼容 MCP 的客户端。
• ✅ 用户身份跟踪：
  • 查询归属（自动）：通过 X-Trino-Client-Tags/Info 标头为查询添加 OAuth 用户标记
  • 用户模拟（可选启用）：通过 X-Trino-User 标头以 OAuth 用户身份执行查询

安装与快速开始

安装：

# 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

运行（本地开发）：

export TRINO_HOST=localhost TRINO_USER=trino
mcp-trino

如需了解使用 OAuth 的生产环境部署，请参阅部署指南和 OAuth 架构。

CLI 模式

mcp-trino 可用作交互式 CLI，类似于 psql 或 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

内置帮助

每条命令都有结构化、便于大模型理解的帮助输出：

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

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

帮助输出遵循 Unix 手册页约定，包含以下部分：NAME、SYNOPSIS、DESCRIPTION、COMMANDS、FLAGS、EXAMPLES、ENVIRONMENT 和 CONFIGURATION。

退出代码

代码	含义
0	成功
1	运行时错误（连接失败、查询错误等）
2	用法错误（未知命令、无效标志、缺少参数）

命名配置

mcp-trino 支持命名连接配置，方便在不同 Trino 环境之间切换。

配置文件 — 支持 YAML（~/.config/trino/config.yaml）和 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

或者使用 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" }
}

如果两个文件都存在，则优先使用 config.json。新配置默认使用 JSON。

配置管理命令：

# 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

配置优先级（从高到低）：

1. CLI 标志（--host、--port 等）
2. --profile 标志
3. TRINO_PROFILE 环境变量
4. 配置文件中的 current 字段
5. 回退到 default 配置
6. 环境变量（TRINO_HOST 等）

环境变量（优先级最低——会被配置和标志覆盖）：

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

密钥管理（推荐）：

密钥仅从环境变量加载。使用密钥 CLI 在启动时通过 Unix 管道注入密钥——应用不会访问你的密钥库：

# 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

有关 1Password、Vault 和 Kubernetes 的配置模式，以及安全注意事项（shell 历史记录、进程列表和环境变量泄漏），请参阅 docs/secrets.md。

REPL 元命令（交互模式下）：

• \help - 显示帮助
• \quit、\exit、\q - 退出 REPL
• \history - 显示命令历史记录
• \catalogs - 列出所有目录
• \schemas [catalog] - 列出架构
• \tables [catalog schema] - 列出表
• \describe <table> - 描述表
• \format <table|json|csv> - 更改输出格式

用法

支持的客户端： Claude Desktop、Claude Code、Cursor、Windsurf、ChatWise

可用工具： execute_query、list_catalogs、list_schemas、list_tables、get_table_schema、explain_query

有关客户端集成和工具文档，请参阅集成指南和工具参考。

配置

关键变量： TRINO_HOST、TRINO_USER、TRINO_SCHEME、MCP_TRANSPORT、OAUTH_PROVIDER

密钥管理： 通过进程环境注入密钥——mcp-trino 会直接读取。有关 1Password、Vault 和 Kubernetes 的配置方案，请参阅 docs/secrets.md。

# 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 配置：

# 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

性能优化：

# Focus AI on specific schemas only (10-20x performance improvement)
export TRINO_ALLOWED_SCHEMAS="hive.analytics,hive.marts,hive.reporting"

用户身份跟踪：

# 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

完整配置请参阅部署指南、OAuth 指南、允许列表指南和用户身份指南。

OAuth 实现

mcp-trino 使用 oauth-mcp-proxy——一个面向 Go MCP 服务的独立 OAuth 2.1 库。

为什么使用独立库？

• ✅ 可在任意 Go MCP 服务中复用
• ✅ 独立测试和版本管理
• ✅ 提供专门的文档和示例
• ✅ 由社区维护的 OAuth 实现

OAuth 详情：

• oauth-mcp-proxy 文档 - 完整的 OAuth 指南
• 提供方配置指南 - Okta、Google、Azure AD
• 安全最佳实践 - 生产环境安全

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

相关项目

• oauth-mcp-proxy - mcp-trino 使用的 OAuth 2.1 身份验证库（可供任何 Go MCP 服务复用）

CI/CD 与发布

本项目使用 GitHub Actions 进行持续集成，并使用 GoReleaser 自动发布。

持续集成检查

我们的 CI 流水线会对所有 PR 和提交到 main 分支的代码执行以下检查：

代码质量

• Lint 检查：使用 golangci-lint 检查常见代码问题和风格违规
• Go 模块验证：确保正确维护 go.mod 和 go.sum
• 格式检查：验证代码是否已使用 gofmt 正确格式化

安全性

• 漏洞扫描：使用 govulncheck 检查依赖项中已知的漏洞
• 依赖项扫描：使用 Trivy 扫描依赖项中的漏洞（CRITICAL、HIGH 和 MEDIUM）
• SBOM 生成：创建软件物料清单，以跟踪依赖项
• SLSA 来源证明：创建可验证的构建来源证明，保障供应链安全

测试

• 单元测试：运行测试，并启用竞态检测和代码覆盖率报告
• 构建验证：确保代码库能够成功构建

CI/CD 安全性

• 最小权限：工作流仅使用所需的最低权限运行
• 固定版本：所有 GitHub Actions 均使用指定版本，以防止供应链攻击
• 依赖项更新：通过 Dependabot 自动更新依赖项

发布流程

更改合并到 main 分支后：

1. 运行 CI 检查，以验证代码质量和安全性
2. 如果检查成功，则自动创建新版本，其中包括：
   • 根据提交消息确定语义化版本号
   • 为多个平台构建二进制文件
   • 将 Docker 镜像发布到 GitHub Container Registry
   • SBOM 和来源证明认证