{
  "markdown": "[![txn2/mcp-trino](docs/images/MCP-trino-logo-banner.svg)](https://mcp-trino.txn2.com)\n\n[![GitHub license](https://img.shields.io/github/license/txn2/mcp-trino.svg)](https://github.com/txn2/mcp-trino/blob/main/LICENSE)\n[![Go Reference](https://pkg.go.dev/badge/github.com/txn2/mcp-trino.svg)](https://pkg.go.dev/github.com/txn2/mcp-trino)\n[![Go Report Card](https://goreportcard.com/badge/github.com/txn2/mcp-trino)](https://goreportcard.com/report/github.com/txn2/mcp-trino)\n[![codecov](https://codecov.io/gh/txn2/mcp-trino/branch/main/graph/badge.svg)](https://codecov.io/gh/txn2/mcp-trino)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/txn2/mcp-trino/badge)](https://scorecard.dev/viewer/?uri=github.com/txn2/mcp-trino)\n[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)\n\n**[mcp-trino.txn2.com](https://mcp-trino.txn2.com)** | **[Installation](https://mcp-trino.txn2.com/server/installation/)** | **[Library Docs](https://mcp-trino.txn2.com/library/)**\n\nA Model Context Protocol (MCP) server for [Trino](https://trino.io/), enabling AI assistants to query and explore data warehouses with optional semantic context from metadata catalogs.\n\nAI assistants excel at querying data but lack organizational context: which tables are trustworthy, what metrics mean, and which columns contain sensitive data. mcp-trino bridges this gap by connecting Trino to AI assistants through the MCP protocol, with an optional semantic layer that surfaces business metadata alongside query results.\n\n## MCP Data Platform Ecosystem\n\nmcp-trino is part of a broader suite of open-source MCP servers designed to work together as a composable data platform. Each component can run standalone or be combined to give AI assistants unified access to storage, query engines, and metadata catalogs.\n\n- [txn2/mcp-data-platform](https://github.com/txn2/mcp-data-platform/)\n- [txn2/mcp-datahub](https://github.com/txn2/mcp-datahub/)\n- [txn2/mcp-s3](https://github.com/txn2/mcp-s3/)\n\n## Core Capabilities\n\n**Composable Architecture**\n- Import as a Go library to build custom MCP servers\n- Add authentication, tenant isolation, audit logging without forking\n- Middleware and interceptor patterns for enterprise requirements\n\n**Semantic Context**\n- Surface business descriptions, ownership, and data quality from metadata catalogs\n- Mark sensitive columns for AI assistants\n- Connect to DataHub, static files, or build custom metadata providers\n\n**Multi-Cluster Connectivity**\n- Query multiple Trino servers from a single MCP installation\n- Unified interface across production, staging, and development environments\n\n**Secure Defaults**\n- Read-only mode prevents accidental data modification\n- Query limits and timeouts prevent runaway operations\n- SLSA Level 3 provenance for supply chain security\n\n## Features\n\n- **Execute SQL Queries**: Run queries with configurable row limits and timeouts\n- **Analyze Execution Plans**: Inspect logical, distributed, and I/O query plans\n- **Discover Schema**: Browse catalogs, schemas, and tables across clusters\n- **Describe Tables**: View column definitions with optional data samples\n- **Enrich with Context**: Surface business metadata, ownership, and data quality\n- **Compose Custom Servers**: Import as a Go library with middleware and interceptors\n\n## Installation\n\n### Homebrew (macOS)\n\n```bash\nbrew install txn2/tap/mcp-trino\n```\n\n### Claude Desktop\n\nClaude Desktop is the GUI application for chatting with Claude. Install the mcp-trino extension to enable Trino queries in your conversations.\n\n**Option 1: One-Click Install (Recommended)**\n\nDownload the `.mcpb` bundle for your Mac from the [releases page](https://github.com/txn2/mcp-trino/releases) and double-click to install:\n\n| Mac Type | Chip | Download |\n|----------|------|----------|\n| MacBook Air/Pro (2020+), Mac Mini (2020+), iMac (2021+), Mac Studio | Apple M1, M2, M3, M4 (arm64) | `mcp-trino_*_darwin_arm64.mcpb` |\n| MacBook Air/Pro (pre-2020), Mac Mini (pre-2020), iMac (pre-2021) | Intel (amd64) | `mcp-trino_*_darwin_amd64.mcpb` |\n\n> **Tip:** Not sure which chip you have? Click  → \"About This Mac\". Look for \"Chip\" (Apple Silicon) or \"Processor\" (Intel).\n\n**Option 2: Manual Configuration**\n\nAdd to your `claude_desktop_config.json` (find via Claude Desktop → Settings → Developer):\n\n```json\n{\n  \"mcpServers\": {\n    \"trino\": {\n      \"command\": \"/opt/homebrew/bin/mcp-trino\",\n      \"env\": {\n        \"TRINO_HOST\": \"trino.example.com\",\n        \"TRINO_USER\": \"your_user\",\n        \"TRINO_PASSWORD\": \"your_password\",\n        \"TRINO_CATALOG\": \"hive\",\n        \"TRINO_SCHEMA\": \"default\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code CLI\n\nClaude Code is the terminal-based coding assistant. Add mcp-trino as an MCP server:\n\n```bash\n# Install via Homebrew first (see above), then:\nclaude mcp add trino \\\n  -e TRINO_HOST=trino.example.com \\\n  -e TRINO_USER=your_user \\\n  -e TRINO_PASSWORD=your_password \\\n  -e TRINO_CATALOG=hive \\\n  -- mcp-trino\n```\n\nOr download and install manually:\n\n```bash\n# Download the latest release for your architecture\ncurl -L https://github.com/txn2/mcp-trino/releases/latest/download/mcp-trino_$(uname -s)_$(uname -m).tar.gz | tar xz\n\n# Add to Claude Code\nclaude mcp add trino \\\n  -e TRINO_HOST=trino.example.com \\\n  -e TRINO_USER=your_user \\\n  -e TRINO_PASSWORD=your_password \\\n  -e TRINO_CATALOG=hive \\\n  -- ./mcp-trino\n```\n\n### Docker\n\n```bash\ndocker run --rm -i \\\n  -e TRINO_HOST=trino.example.com \\\n  -e TRINO_USER=your_user \\\n  -e TRINO_PASSWORD=your_password \\\n  ghcr.io/txn2/mcp-trino:latest\n```\n\n### Go Install\n\n```bash\ngo install github.com/txn2/mcp-trino/cmd/mcp-trino@latest\n```\n\n### Download Binary\n\nDownload pre-built binaries from the [releases page](https://github.com/txn2/mcp-trino/releases). All releases are signed with [Cosign](https://github.com/sigstore/cosign) and include [SLSA provenance](https://slsa.dev/).\n\n### As a Library\n\n```bash\ngo get github.com/txn2/mcp-trino\n```\n\n## Quick Start\n\n### Multiple Trino Servers\n\nYou can configure multiple Trino instances with different names:\n\n```bash\n# Production\nclaude mcp add trino-prod \\\n  -e TRINO_HOST=trino.prod.example.com \\\n  -e TRINO_USER=prod_user \\\n  -- mcp-trino\n\n# Staging\nclaude mcp add trino-staging \\\n  -e TRINO_HOST=trino.staging.example.com \\\n  -e TRINO_USER=staging_user \\\n  -- mcp-trino\n```\n\n### Standalone Server\n\n```bash\nexport TRINO_HOST=trino.example.com\nexport TRINO_USER=your_user\nexport TRINO_PASSWORD=your_password\nmcp-trino\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `trino_query` | Execute read-only SQL queries (SELECT, SHOW, DESCRIBE) with limit/timeout control |\n| `trino_execute` | Execute any SQL including write operations (INSERT, UPDATE, DELETE, CREATE, DROP) |\n| `trino_explain` | Get execution plans (logical/distributed/io/validate) |\n| `trino_browse` | Browse catalog hierarchy: list catalogs, schemas, or tables |\n| `trino_describe_table` | Get columns, sample data, and semantic context (if configured) |\n| `trino_list_connections` | List all configured server connections |\n\n## Semantic Layer\n\nAI agents operate more reliably when they understand organizational context: not just table structures, but which datasets are production-ready, what business terms mean, and which columns require careful handling.\n\nmcp-trino's semantic layer integrates with metadata catalogs to surface this context alongside query results:\n\n| Metadata | Description |\n|----------|-------------|\n| **Descriptions** | Business-friendly explanations of tables and columns |\n| **Ownership** | Data stewards and technical owners |\n| **Tags & Domains** | Classification labels and business domains |\n| **Glossary Terms** | Links to formal business definitions |\n| **Data Quality** | Freshness scores and quality metrics |\n| **Sensitivity** | PII and sensitive data markers at column level |\n| **Lineage** | Upstream and downstream data dependencies |\n\n### Providers\n\n| Provider | Description |\n|----------|-------------|\n| **DataHub** | Connect to DataHub's GraphQL API for enterprise metadata |\n| **Static Files** | Load metadata from YAML or JSON files with hot-reload |\n| **Custom** | Implement the `semantic.Provider` interface for any catalog |\n\nSee the [Semantic Layer Documentation](https://mcp-trino.txn2.com/semantic/) for configuration, caching, and custom provider development.\n\n## Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `TRINO_HOST` | Trino server hostname | `localhost` |\n| `TRINO_PORT` | Trino server port | `443` (SSL) / `8080` |\n| `TRINO_USER` | Authentication username | (required) |\n| `TRINO_PASSWORD` | Authentication password | (optional) |\n| `TRINO_CATALOG` | Default catalog | `memory` |\n| `TRINO_SCHEMA` | Default schema | `default` |\n| `TRINO_SSL` | Enable HTTPS | `true` for remote hosts |\n| `TRINO_SSL_VERIFY` | Verify SSL certificates | `true` |\n| `TRINO_TIMEOUT` | Query timeout (seconds) | `120` |\n| `TRINO_SOURCE` | Client identifier | `mcp-trino` |\n| `TRINO_ADDITIONAL_SERVERS` | Additional servers (JSON) | (optional) |\n\n### Multi-Server Configuration\n\nConnect to multiple Trino servers from a single installation. Configure your primary server with the standard environment variables, then add additional servers via JSON:\n\n```bash\nexport TRINO_HOST=prod.trino.example.com\nexport TRINO_USER=admin\nexport TRINO_PASSWORD=secret\nexport TRINO_ADDITIONAL_SERVERS='{\n  \"staging\": {\"host\": \"staging.trino.example.com\"},\n  \"dev\": {\"host\": \"localhost\", \"port\": 8080, \"ssl\": false}\n}'\n```\n\nAdditional servers inherit credentials and settings from the primary server unless overridden:\n\n```json\n{\n  \"staging\": {\n    \"host\": \"staging.trino.example.com\",\n    \"user\": \"staging_user\",\n    \"catalog\": \"iceberg\"\n  },\n  \"dev\": {\n    \"host\": \"localhost\",\n    \"port\": 8080,\n    \"ssl\": false,\n    \"user\": \"admin\"\n  }\n}\n```\n\nUse the `connection` parameter in any tool to target a specific server:\n\n```\n\"Query the staging server: SELECT * FROM users LIMIT 10\"\n→ trino_query(sql=\"...\", connection=\"staging\")\n```\n\nUse `trino_list_connections` to discover available connections.\n\n### File-Based Configuration\n\nFor production deployments using Kubernetes ConfigMaps, Vault, or other secret management systems, mcp-trino supports file-based configuration:\n\n```yaml\n# config.yaml\ntrino:\n  host: trino.example.com\n  port: 443\n  user: ${TRINO_USER}           # Supports env var expansion\n  password: ${TRINO_PASSWORD}   # Secrets can come from env\n  catalog: hive\n  schema: default\n  ssl: true\n  timeout: 120s\n\ntoolkit:\n  default_limit: 1000\n  max_limit: 10000\n  default_timeout: 120s\n  max_timeout: 300s\n\nextensions:\n  logging: true\n  readonly: true\n  errors: true\n```\n\nLoad configuration in your custom server:\n\n```go\nimport \"github.com/txn2/mcp-trino/pkg/extensions\"\n\n// Load from file with env var overrides\ncfg, err := extensions.LoadConfig(\"/etc/mcp-trino/config.yaml\")\n\n// Convert to individual configs\nclientCfg := cfg.ClientConfig()\ntoolsCfg := cfg.ToolsConfig()\nextCfg := cfg.ExtConfig()\n```\n\n## Using as a Library\n\nmcp-trino is designed to be composable. You can import its tools into your own MCP server:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n\n    \"github.com/modelcontextprotocol/go-sdk/mcp\"\n    \"github.com/txn2/mcp-trino/pkg/client\"\n    \"github.com/txn2/mcp-trino/pkg/tools\"\n)\n\nfunc main() {\n    // Create your MCP server\n    server := mcp.NewServer(&mcp.Implementation{\n        Name:    \"my-data-server\",\n        Version: \"1.0.0\",\n    }, nil)\n\n    // Create Trino client\n    trinoClient, err := client.New(client.Config{\n        Host:    \"trino.example.com\",\n        Port:    443,\n        User:    \"service_user\",\n        SSL:     true,\n        Catalog: \"hive\",\n        Schema:  \"analytics\",\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer trinoClient.Close()\n\n    // Add Trino tools to your server\n    toolkit := tools.NewToolkit(trinoClient, tools.Config{\n        DefaultLimit: 1000,\n        MaxLimit:     10000,\n    })\n    toolkit.RegisterAll(server)\n\n    // Add your own custom tools here...\n    // mcp.AddTool(server, &mcp.Tool{...}, handler)\n\n    // Run the server\n    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n## Extensions\n\nThe standalone server includes optional extensions that can be enabled via environment variables:\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_TRINO_EXT_LOGGING` | `false` | Structured JSON logging of tool calls |\n| `MCP_TRINO_EXT_METRICS` | `false` | In-memory metrics collection |\n| `MCP_TRINO_EXT_READONLY` | `true` | Block modification statements (INSERT, UPDATE, DELETE, etc.) |\n| `MCP_TRINO_EXT_QUERYLOG` | `false` | Log all SQL queries for audit |\n| `MCP_TRINO_EXT_METADATA` | `false` | Add execution metadata footer to results |\n| `MCP_TRINO_EXT_ERRORS` | `true` | Add helpful hints to error messages |\n\n### Using Extensions in Custom Servers\n\n```go\nimport (\n    \"github.com/txn2/mcp-trino/pkg/extensions\"\n    \"github.com/txn2/mcp-trino/pkg/tools\"\n)\n\n// Load extension config from environment\nextCfg := extensions.FromEnv()\n\n// Or configure programmatically\nextCfg := extensions.Config{\n    EnableLogging:   true,\n    EnableReadOnly:  true,\n    EnableErrorHelp: true,\n}\n\n// Build toolkit options from extensions\ntoolkitOpts := extensions.BuildToolkitOptions(extCfg)\n\n// Create toolkit with extensions\ntoolkit := tools.NewToolkit(trinoClient, toolsCfg, toolkitOpts...)\n```\n\n### Custom Middleware and Interceptors\n\nYou can create custom middleware, interceptors, and transformers:\n\n```go\n// Custom middleware for authentication\nauthMiddleware := tools.MiddlewareFunc{\n    BeforeFn: func(ctx context.Context, tc *tools.ToolContext) (context.Context, error) {\n        // Validate user permissions\n        return ctx, nil\n    },\n}\n\n// Custom interceptor for tenant isolation\ntenantInterceptor := tools.QueryInterceptorFunc(\n    func(ctx context.Context, sql string, toolName tools.ToolName) (string, error) {\n        // Add WHERE tenant_id = ? clause\n        return sql, nil\n    },\n)\n\n// Apply to toolkit\ntoolkit := tools.NewToolkit(client, cfg,\n    tools.WithMiddleware(authMiddleware),\n    tools.WithQueryInterceptor(tenantInterceptor),\n)\n```\n\n## Security Considerations\n\n- **Credentials**: Store passwords in environment variables or secret managers\n- **Query Limits**: Default 1000 rows, max 10000 to prevent data exfiltration\n- **Timeouts**: Default 120s timeout prevents runaway queries\n- **Read-Only**: ReadOnly interceptor enabled by default blocks modification statements\n- **Access Control**: Configure Trino roles and catalog access for defense in depth\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/txn2/mcp-trino.git\ncd mcp-trino\n\n# Build\nmake build\n\n# Run tests\nmake test\n\n# Run linter\nmake lint\n\n# Run all checks\nmake verify\n\n# Run with a local Trino (e.g., via Docker)\nmake docker-trino\nexport TRINO_HOST=localhost\nexport TRINO_PORT=8080\nexport TRINO_USER=admin\nexport TRINO_SSL=false\n./mcp-trino\n```\n\n## Contributing\n\nWe welcome contributions for bug fixes, tests, and documentation. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[Apache License 2.0](LICENSE)\n\n---\n\nOpen source by [Craig Johnston](https://twitter.com/cjimti), sponsored by [Deasil Works, Inc.](https://deasil.works/)\n",
  "bytes": 15400,
  "sha": "527659c6b024d18eb18319d4625ea8b400a2b7c8237101596a59e3ca2169ce20",
  "repo_slug": "txn2/mcp-trino",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_txn2_mcp_trino_5fffde0e/readme"
}