mcp-trino

mcp-trino.txn2.com | 安装 | 库文档

面向 Trino 的模型上下文协议（MCP）服务，让 AI 助手能够查询和探索数据仓库，并可选择使用元数据目录中的语义上下文。

AI 助手擅长查询数据，却缺少组织层面的背景信息：哪些表值得信赖、指标的含义是什么，以及哪些列包含敏感数据。mcp-trino 通过 MCP 协议将 Trino 连接到 AI 助手，弥补这一不足；可选的语义层还能在查询结果中呈现业务元数据。

MCP 数据平台生态系统

mcp-trino 是一套更广泛的开源 MCP 服务的一部分，这些服务旨在协同工作，组成可组合的数据平台。每个组件都可以独立运行，也可以组合使用，为 AI 助手提供统一的存储、查询引擎和元数据目录访问能力。

• txn2/mcp-data-platform
• txn2/mcp-datahub
• txn2/mcp-s3

核心能力

可组合架构

• 作为 Go 库导入，用于构建自定义 MCP 服务
• 无需分叉即可添加身份验证、租户隔离和审计日志
• 通过中间件和拦截器模式满足企业需求

语义上下文

• 从元数据目录呈现业务描述、所有权和数据质量信息
• 为 AI 助手标记敏感列
• 连接到 DataHub、静态文件，或构建自定义元数据提供程序

多集群连接

• 从单个 MCP 安装实例查询多个 Trino 服务
• 在生产、预发布和开发环境之间提供统一接口

安全默认设置

• 只读模式可防止意外修改数据
• 查询限制和超时设置可防止操作失控
• 提供 SLSA Level 3 来源证明，确保供应链安全

功能

• 执行 SQL 查询：运行查询，并配置行数限制和超时时间
• 分析执行计划：检查逻辑、分布式和 I/O 查询计划
• 发现架构：浏览各集群中的目录、架构和表
• 描述表：查看列定义，并可选择包含数据样例
• 丰富上下文：呈现业务元数据、所有权和数据质量信息
• 组合自定义服务：作为 Go 库导入，并使用中间件和拦截器

安装

Homebrew（macOS）

brew install txn2/tap/mcp-trino

Claude Desktop

Claude Desktop 是用于与 Claude 聊天的 GUI 应用程序。安装 mcp-trino 扩展，即可在对话中启用 Trino 查询。

选项 1：一键安装（推荐）

从 releases 页面下载适用于 Mac 的 .mcpb 捆绑包，然后双击安装：

Mac 类型	芯片	下载
MacBook Air/Pro（2020 年及以后）、Mac Mini（2020 年及以后）、iMac（2021 年及以后）、Mac Studio	Apple M1、M2、M3、M4（arm64）	mcp-trino_*_darwin_arm64.mcpb
MacBook Air/Pro（2020 年以前）、Mac Mini（2020 年以前）、iMac（2021 年以前）	Intel（amd64）	mcp-trino_*_darwin_amd64.mcpb

提示： 不确定自己的芯片型号？点击 →“关于本机”。查找“芯片”（Apple Silicon）或“处理器”（Intel）。

选项 2：手动配置

将以下内容添加到 claude_desktop_config.json（可通过 Claude Desktop → Settings → Developer 找到）：

{
  "mcpServers": {
    "trino": {
      "command": "/opt/homebrew/bin/mcp-trino",
      "env": {
        "TRINO_HOST": "trino.example.com",
        "TRINO_USER": "your_user",
        "TRINO_PASSWORD": "your_password",
        "TRINO_CATALOG": "hive",
        "TRINO_SCHEMA": "default"
      }
    }
  }
}

Claude Code CLI

Claude Code 是基于终端的编码助手。将 mcp-trino 添加为 MCP 服务：

# Install via Homebrew first (see above), then:
claude mcp add trino \
  -e TRINO_HOST=trino.example.com \
  -e TRINO_USER=your_user \
  -e TRINO_PASSWORD=your_password \
  -e TRINO_CATALOG=hive \
  -- mcp-trino

或者手动下载并安装：

# Download the latest release for your architecture
curl -L https://github.com/txn2/mcp-trino/releases/latest/download/mcp-trino_$(uname -s)_$(uname -m).tar.gz | tar xz

# Add to Claude Code
claude mcp add trino \
  -e TRINO_HOST=trino.example.com \
  -e TRINO_USER=your_user \
  -e TRINO_PASSWORD=your_password \
  -e TRINO_CATALOG=hive \
  -- ./mcp-trino

Docker

docker run --rm -i \
  -e TRINO_HOST=trino.example.com \
  -e TRINO_USER=your_user \
  -e TRINO_PASSWORD=your_password \
  ghcr.io/txn2/mcp-trino:latest

Go 安装

go install github.com/txn2/mcp-trino/cmd/mcp-trino@latest

下载二进制文件

从 releases 页面下载预构建的二进制文件。所有版本均使用 Cosign 签名，并附带 SLSA 来源证明。

作为库使用

go get github.com/txn2/mcp-trino

快速开始

多个 Trino 服务

你可以使用不同名称配置多个 Trino 实例：

# Production
claude mcp add trino-prod \
  -e TRINO_HOST=trino.prod.example.com \
  -e TRINO_USER=prod_user \
  -- mcp-trino

# Staging
claude mcp add trino-staging \
  -e TRINO_HOST=trino.staging.example.com \
  -e TRINO_USER=staging_user \
  -- mcp-trino

独立服务

export TRINO_HOST=trino.example.com
export TRINO_USER=your_user
export TRINO_PASSWORD=your_password
mcp-trino

工具

工具	描述
trino_query	执行只读 SQL 查询（SELECT、SHOW、DESCRIBE），并控制结果数量上限和超时
trino_execute	执行任意 SQL，包括写入操作（INSERT、UPDATE、DELETE、CREATE、DROP）
trino_explain	获取执行计划（logical/distributed/io/validate）
trino_browse	浏览目录层级：列出目录、架构或表
trino_describe_table	获取列、样例数据和语义上下文（如已配置）
trino_list_connections	列出所有已配置的服务连接

语义层

当 AI Agent 了解组织上下文时，运作会更加可靠：不仅要了解表结构，还要知道哪些数据集已准备好用于生产、业务术语的含义，以及哪些列需要谨慎处理。

mcp-trino 的语义层与元数据目录集成，可在查询结果旁提供这些上下文信息：

元数据	描述
描述	面向业务的表和列说明
所有权	数据管理员和技术负责人
标签与领域	分类标签和业务领域
术语表条目	正式业务定义的链接
数据质量	新鲜度评分和质量指标
敏感性	列级 PII 和敏感数据标记
数据沿袭	上游和下游数据依赖关系

提供方

提供方	描述
DataHub	连接到 DataHub 的 GraphQL API，以获取企业元数据
静态文件	从 YAML 或 JSON 文件加载元数据，并支持热重载
自定义	为任意目录实现 semantic.Provider 接口

有关配置、缓存和自定义提供方开发，请参阅语义层文档。

配置

环境变量	描述	默认值
TRINO_HOST	Trino 服务主机名	localhost
TRINO_PORT	Trino 服务端口	443（SSL）/ 8080
TRINO_USER	身份验证用户名	（必填）
TRINO_PASSWORD	身份验证密码	（可选）
TRINO_CATALOG	默认目录	memory
TRINO_SCHEMA	默认架构	default
TRINO_SSL	启用 HTTPS	对远程主机为 true
TRINO_SSL_VERIFY	验证 SSL 证书	true
TRINO_TIMEOUT	查询超时时间（秒）	120
TRINO_SOURCE	客户端标识符	mcp-trino
TRINO_ADDITIONAL_SERVERS	其他服务（JSON）	（可选）

多服务配置

通过单个安装连接到多个 Trino 服务。使用标准环境变量配置主服务，然后通过 JSON 添加其他服务：

export TRINO_HOST=prod.trino.example.com
export TRINO_USER=admin
export TRINO_PASSWORD=secret
export TRINO_ADDITIONAL_SERVERS='{
  "staging": {"host": "staging.trino.example.com"},
  "dev": {"host": "localhost", "port": 8080, "ssl": false}
}'

除非另行指定，否则其他服务会继承主服务的凭据和设置：

{
  "staging": {
    "host": "staging.trino.example.com",
    "user": "staging_user",
    "catalog": "iceberg"
  },
  "dev": {
    "host": "localhost",
    "port": 8080,
    "ssl": false,
    "user": "admin"
  }
}

在任何工具中使用 connection 参数来指定目标服务：

"Query the staging server: SELECT * FROM users LIMIT 10"
→ trino_query(sql="...", connection="staging")

使用 trino_list_connections 发现可用连接。

基于文件的配置

对于使用 Kubernetes ConfigMaps、Vault 或其他密钥管理系统的生产部署，mcp-trino 支持基于文件的配置：

# config.yaml
trino:
  host: trino.example.com
  port: 443
  user: ${TRINO_USER}           # Supports env var expansion
  password: ${TRINO_PASSWORD}   # Secrets can come from env
  catalog: hive
  schema: default
  ssl: true
  timeout: 120s

toolkit:
  default_limit: 1000
  max_limit: 10000
  default_timeout: 120s
  max_timeout: 300s

extensions:
  logging: true
  readonly: true
  errors: true

在自定义服务中加载配置：

import "github.com/txn2/mcp-trino/pkg/extensions"

// Load from file with env var overrides
cfg, err := extensions.LoadConfig("/etc/mcp-trino/config.yaml")

// Convert to individual configs
clientCfg := cfg.ClientConfig()
toolsCfg := cfg.ToolsConfig()
extCfg := cfg.ExtConfig()

用作库

mcp-trino 专为组合使用而设计。你可以将其工具导入自己的 MCP 服务：

package main

import (
    "context"
    "log"

    "github.com/modelcontextprotocol/go-sdk/mcp"
    "github.com/txn2/mcp-trino/pkg/client"
    "github.com/txn2/mcp-trino/pkg/tools"
)

func main() {
    // Create your MCP server
    server := mcp.NewServer(&mcp.Implementation{
        Name:    "my-data-server",
        Version: "1.0.0",
    }, nil)

    // Create Trino client
    trinoClient, err := client.New(client.Config{
        Host:    "trino.example.com",
        Port:    443,
        User:    "service_user",
        SSL:     true,
        Catalog: "hive",
        Schema:  "analytics",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer trinoClient.Close()

    // Add Trino tools to your server
    toolkit := tools.NewToolkit(trinoClient, tools.Config{
        DefaultLimit: 1000,
        MaxLimit:     10000,
    })
    toolkit.RegisterAll(server)

    // Add your own custom tools here...
    // mcp.AddTool(server, &mcp.Tool{...}, handler)

    // Run the server
    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

扩展

独立服务包含可选扩展，可通过环境变量启用：

环境变量	默认值	描述
MCP_TRINO_EXT_LOGGING	false	对工具调用进行结构化 JSON 日志记录
MCP_TRINO_EXT_METRICS	false	在内存中收集指标
MCP_TRINO_EXT_READONLY	true	阻止修改语句（INSERT、UPDATE、DELETE 等）
MCP_TRINO_EXT_QUERYLOG	false	记录所有 SQL 查询以供审计
MCP_TRINO_EXT_METADATA	false	在结果中添加执行元数据页脚
MCP_TRINO_EXT_ERRORS	true	在错误消息中添加实用提示

在自定义服务中使用扩展

import (
    "github.com/txn2/mcp-trino/pkg/extensions"
    "github.com/txn2/mcp-trino/pkg/tools"
)

// Load extension config from environment
extCfg := extensions.FromEnv()

// Or configure programmatically
extCfg := extensions.Config{
    EnableLogging:   true,
    EnableReadOnly:  true,
    EnableErrorHelp: true,
}

// Build toolkit options from extensions
toolkitOpts := extensions.BuildToolkitOptions(extCfg)

// Create toolkit with extensions
toolkit := tools.NewToolkit(trinoClient, toolsCfg, toolkitOpts...)

自定义中间件和拦截器

你可以创建自定义中间件、拦截器和转换器：

// Custom middleware for authentication
authMiddleware := tools.MiddlewareFunc{
    BeforeFn: func(ctx context.Context, tc *tools.ToolContext) (context.Context, error) {
        // Validate user permissions
        return ctx, nil
    },
}

// Custom interceptor for tenant isolation
tenantInterceptor := tools.QueryInterceptorFunc(
    func(ctx context.Context, sql string, toolName tools.ToolName) (string, error) {
        // Add WHERE tenant_id = ? clause
        return sql, nil
    },
)

// Apply to toolkit
toolkit := tools.NewToolkit(client, cfg,
    tools.WithMiddleware(authMiddleware),
    tools.WithQueryInterceptor(tenantInterceptor),
)

安全注意事项

• 凭据：将密码存储在环境变量或密钥管理器中
• 查询限制：默认最多 1000 行，最高 10000 行，以防止数据泄露
• 超时：默认 120s 超时可防止查询失控
• 只读：默认启用的 ReadOnly 拦截器会阻止修改语句
• 访问控制：配置 Trino 角色和目录访问权限，以实现纵深防御

开发

# Clone the repository
git clone https://github.com/txn2/mcp-trino.git
cd mcp-trino

# Build
make build

# Run tests
make test

# Run linter
make lint

# Run all checks
make verify

# Run with a local Trino (e.g., via Docker)
make docker-trino
export TRINO_HOST=localhost
export TRINO_PORT=8080
export TRINO_USER=admin
export TRINO_SSL=false
./mcp-trino

贡献

欢迎贡献 Bug 修复、测试和文档。请参阅 贡献指南 了解相关指引。

许可证

Apache License 2.0

---

由 Craig Johnston 开源，赞助方为 Deasil Works, Inc.