{"id":27311688,"url":"https://github.com/tuannvm/mcp-trino","last_synced_at":"2026-05-02T11:42:53.685Z","repository":{"id":287092595,"uuid":"963330420","full_name":"tuannvm/mcp-trino","owner":"tuannvm","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-09T23:27:18.000Z","size":73,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T23:29:18.605Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuannvm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-09T14:10:52.000Z","updated_at":"2025-04-09T22:44:27.000Z","dependencies_parsed_at":"2025-04-09T23:39:34.547Z","dependency_job_id":null,"html_url":"https://github.com/tuannvm/mcp-trino","commit_stats":null,"previous_names":["tuannvm/mcp-trino"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Fmcp-trino","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Fmcp-trino/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Fmcp-trino/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuannvm%2Fmcp-trino/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuannvm","download_url":"https://codeload.github.com/tuannvm/mcp-trino/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199247,"owners_count":21063641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-12T06:03:07.067Z","updated_at":"2026-05-02T11:42:53.679Z","avatar_url":"https://github.com/tuannvm.png","language":"Go","funding_links":[],"categories":["Databases","Database \u0026 Messaging MCP Servers","サーバー実装","Community Servers","📚 Projects (1974 total)","⚙️ DevOps","Cloud Services","カテゴリ","MCP Servers \u0026 Protocol","Server Implementations"],"sub_categories":["SQL Databases","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eデータベース","MCP Servers","How to Submit","🗄️ \u003ca name=\"database--sql\"\u003e\u003c/a\u003eデータベース・SQL","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases"],"readme":"# Trino MCP Server in Go\n\nA high-performance Model Context Protocol (MCP) server for Trino implemented in Go. This project enables AI assistants to seamlessly interact with Trino's distributed SQL query engine through standardized MCP tools.\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/tuannvm/mcp-trino/build.yml?branch=main\u0026label=CI%2FCD\u0026logo=github)](https://github.com/tuannvm/mcp-trino/actions/workflows/build.yml)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/tuannvm/mcp-trino?logo=go)](https://github.com/tuannvm/mcp-trino/blob/main/go.mod)\n[![Trivy Scan](https://img.shields.io/github/actions/workflow/status/tuannvm/mcp-trino/build.yml?branch=main\u0026label=Trivy%20Security%20Scan\u0026logo=aquasec)](https://github.com/tuannvm/mcp-trino/actions/workflows/build.yml)\n[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)\n[![Go Report Card](https://goreportcard.com/badge/github.com/tuannvm/mcp-trino)](https://goreportcard.com/report/github.com/tuannvm/mcp-trino)\n[![Go Reference](https://pkg.go.dev/badge/github.com/tuannvm/mcp-trino.svg)](https://pkg.go.dev/github.com/tuannvm/mcp-trino)\n[![Docker Image](https://img.shields.io/github/v/release/tuannvm/mcp-trino?sort=semver\u0026label=GHCR\u0026logo=docker)](https://github.com/tuannvm/mcp-trino/pkgs/container/mcp-trino)\n[![GitHub Release](https://img.shields.io/github/v/release/tuannvm/mcp-trino?sort=semver)](https://github.com/tuannvm/mcp-trino/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/tuannvm/mcp-trino)](https://archestra.ai/mcp-catalog/tuannvm__mcp-trino)\n\n## Overview\n\nThis project implements a Model Context Protocol (MCP) server for Trino in Go. It enables AI assistants to access Trino's distributed SQL query engine through standardized MCP tools.\n\nTrino (formerly PrestoSQL) is a powerful distributed SQL query engine designed for fast analytics on large datasets.\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"AI Clients\"\n        CC[Claude Code]\n        CD[Claude Desktop]\n        CR[Cursor]\n        WS[Windsurf]\n        CW[ChatWise]\n    end\n    \n    subgraph \"Authentication (Optional)\"\n        OP[OAuth Provider\u003cbr/\u003eOkta/Google/Azure AD]\n        JWT[JWT Tokens]\n    end\n    \n    subgraph \"MCP Server (mcp-trino)\"\n        HTTP[HTTP Transport\u003cbr/\u003e/mcp endpoint]\n        STDIO[STDIO Transport]\n        AUTH[OAuth Middleware]\n        TOOLS[MCP Tools\u003cbr/\u003e• execute_query\u003cbr/\u003e• list_catalogs\u003cbr/\u003e• list_schemas\u003cbr/\u003e• list_tables\u003cbr/\u003e• get_table_schema\u003cbr/\u003e• explain_query]\n    end\n    \n    subgraph \"Data Layer\"\n        TRINO[Trino Cluster\u003cbr/\u003eDistributed SQL Engine]\n        CATALOGS[Data Sources\u003cbr/\u003e• PostgreSQL\u003cbr/\u003e• MySQL\u003cbr/\u003e• S3/Hive\u003cbr/\u003e• BigQuery\u003cbr/\u003e• MongoDB]\n    end\n    \n    %% Connections\n    CC -.-\u003e|OAuth Flow| OP\n    OP -.-\u003e|JWT Token| JWT\n    \n    CC --\u003e|HTTP + JWT| HTTP\n    CD --\u003e|STDIO| STDIO\n    CR --\u003e|HTTP + JWT| HTTP\n    WS --\u003e|STDIO| STDIO\n    CW --\u003e|HTTP + JWT| HTTP\n    \n    HTTP --\u003e AUTH\n    AUTH --\u003e|Validated| TOOLS\n    STDIO --\u003e TOOLS\n    \n    TOOLS --\u003e|SQL Queries| TRINO\n    TRINO --\u003e CATALOGS\n    \n    %% Styling\n    classDef client fill:#e1f5fe\n    classDef auth fill:#f3e5f5\n    classDef server fill:#e8f5e8\n    classDef data fill:#fff3e0\n    \n    class CC,CD,CR,WS,CW client\n    class OP,JWT auth\n    class HTTP,STDIO,AUTH,TOOLS server\n    class TRINO,CATALOGS data\n```\n\n**Key Components:**\n\n- **AI Clients**: Various MCP-compatible applications\n- **Authentication**: Optional OAuth 2.0 with OIDC providers\n- **MCP Server**: Go-based server with dual transport support\n- **CLI Mode**: Interactive SQL shell for direct Trino access (psql-like)\n- **Data Layer**: Trino cluster connecting to multiple data sources\n\n## Features\n\n- ✅ **Dual Mode**: Works as both MCP server AND interactive CLI\n  - **CLI Mode**: psql-like interactive SQL shell for direct Trino access\n  - **MCP Mode**: Full MCP server for AI assistant integration\n- ✅ MCP server implementation in Go\n- ✅ Trino SQL query execution through MCP tools\n- ✅ Catalog, schema, and table discovery\n- ✅ Docker container support\n- ✅ Supports both STDIO and HTTP transports\n- ✅ OAuth 2.1 authentication via [oauth-mcp-proxy](https://github.com/tuannvm/oauth-mcp-proxy) library\n  - **4 Providers**: HMAC, Okta, Google, Azure AD\n  - **Native mode**: Client handles OAuth directly (zero server-side secrets)\n  - **Proxy mode**: Server proxies OAuth flow for simple clients\n  - **Production-ready**: Token caching, PKCE, defense-in-depth security\n  - **Reusable**: OAuth library available for any Go MCP server\n- ✅ StreamableHTTP support with JWT authentication (upgraded from SSE)\n- ✅ Backward compatibility with SSE endpoints\n- ✅ Compatible with Cursor, Claude Desktop, Windsurf, ChatWise, and any MCP-compatible clients.\n- ✅ User Identity Tracking:\n  - **Query Attribution** (automatic): Tags queries with OAuth user via `X-Trino-Client-Tags/Info` headers\n  - **User Impersonation** (opt-in): Execute queries as OAuth user via `X-Trino-User` header\n\n## Installation \u0026 Quick Start\n\n**Install:**\n\n```bash\n# Homebrew\nbrew install tuannvm/mcp/mcp-trino\n\n# Or one-liner (macOS/Linux)\ncurl -fsSL https://raw.githubusercontent.com/tuannvm/mcp-trino/main/install.sh | bash\n```\n\n**Run (Local Development):**\n\n```bash\nexport TRINO_HOST=localhost TRINO_USER=trino\nmcp-trino\n```\n\nFor production deployment with OAuth, see [Deployment Guide](docs/deployment.md) and [OAuth Architecture](docs/oauth.md).\n\n## CLI Mode\n\nmcp-trino can be used as an interactive CLI similar to `psql` or the Trino CLI:\n\n```bash\n# Interactive REPL mode\nmcp-trino --interactive\n\n# Execute a query directly\nmcp-trino query \"SELECT * FROM my_table LIMIT 10\"\n\n# List catalogs, schemas, tables\nmcp-trino catalogs\nmcp-trino schemas my_catalog\nmcp-trino tables my_catalog my_schema\n\n# Describe a table\nmcp-trino describe my_catalog.my_schema.my_table\n\n# Explain a query\nmcp-trino explain \"SELECT COUNT(*) FROM my_table\"\n\n# Output formats\nmcp-trino --format json query \"SELECT 1\"\nmcp-trino --format csv query \"SELECT 1\"\nmcp-trino --format table query \"SELECT 1\"  # default\n```\n\n### Built-in Help\n\nEvery command has structured, LLM-friendly help output:\n\n```bash\n# Main help with all commands, flags, examples, and environment variables\nmcp-trino --help\n\n# Per-subcommand help\nmcp-trino query --help\nmcp-trino describe --help\n```\n\nHelp output follows Unix man-page conventions with sections: NAME, SYNOPSIS, DESCRIPTION, COMMANDS, FLAGS, EXAMPLES, ENVIRONMENT, and CONFIGURATION.\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | Runtime error (connection failed, query error, etc.) |\n| 2 | Usage error (unknown command, invalid flags, missing arguments) |\n\n### Named Profiles\n\nmcp-trino supports named connection profiles for easy switching between Trino environments.\n\n**Configuration File** — supports both YAML (`~/.config/trino/config.yaml`) and JSON (`~/.config/trino/config.json`):\n\n```yaml\n# ~/.config/trino/config.yaml\ncurrent: prod\n\nprofiles:\n  prod:\n    host: trino.example.com\n    port: 443\n    user: prod_user\n    password: prod_password\n    catalog: hive\n    schema: analytics\n    ssl:\n      enabled: true\n      insecure: false\n\n  dev:\n    host: localhost\n    port: 8080\n    user: trino\n    catalog: memory\n    schema: default\n\n  staging:\n    host: staging-trino.example.com\n    port: 443\n    user: staging_user\n\noutput:\n  format: table\n```\n\nOr equivalently in JSON:\n\n```json\n{\n  \"current\": \"prod\",\n  \"profiles\": {\n    \"prod\": {\n      \"host\": \"trino.example.com\",\n      \"port\": 443,\n      \"user\": \"prod_user\",\n      \"catalog\": \"hive\",\n      \"ssl\": { \"enabled\": true }\n    },\n    \"dev\": {\n      \"host\": \"localhost\",\n      \"port\": 8080,\n      \"user\": \"trino\"\n    }\n  },\n  \"output\": { \"format\": \"table\" }\n}\n```\n\nWhen both files exist, `config.json` takes precedence. New configs default to JSON.\n\n**Profile Management Commands:**\n\n```bash\n# List all profiles\nmcp-trino config profile list\n\n# Set default profile\nmcp-trino config profile use prod\n\n# Show profile details\nmcp-trino config profile show staging\n\n# Use a specific profile (overrides config file)\nmcp-trino --profile dev catalogs\n```\n\n**Configuration Precedence** (highest to lowest):\n1. CLI flags (`--host`, `--port`, etc.)\n2. `--profile` flag\n3. `TRINO_PROFILE` environment variable\n4. `current` field in config file\n5. `default` profile fallback\n6. Environment variables (`TRINO_HOST`, etc.)\n\n**Environment Variables** (lowest priority - overridden by profiles and flags):\n\n```bash\nexport TRINO_HOST=trino.example.com\nexport TRINO_PORT=443\nexport TRINO_USER=myuser\nexport TRINO_PASSWORD=mypass\nexport TRINO_CATALOG=hive\nexport TRINO_SCHEMA=analytics\nexport TRINO_SSL=true\n```\n\n**Secret Management** (recommended):\n\nSecrets are loaded purely from environment variables. Use a secrets CLI to inject them via Unix piping at launch time — the app never touches your vault:\n\n```bash\n# 1Password CLI — resolves op:// references in an env file\nop run --env-file=.env -- mcp-trino\n\n# Or inline per-variable\nTRINO_PASSWORD=$(op read 'op://Engineering/Trino/password') mcp-trino\n```\n\nSee [docs/secrets.md](docs/secrets.md) for 1Password, Vault, and Kubernetes patterns, and for security nuances (shell-history, process-list, and env-var leakage).\n\n**REPL Meta-Commands** (in interactive mode):\n- `\\help` - Show help\n- `\\quit`, `\\exit`, `\\q` - Exit REPL\n- `\\history` - Show command history\n- `\\catalogs` - List all catalogs\n- `\\schemas [catalog]` - List schemas\n- `\\tables [catalog schema]` - List tables\n- `\\describe \u003ctable\u003e` - Describe table\n- `\\format \u003ctable|json|csv\u003e` - Change output format\n\n## Usage\n\n**Supported Clients:** Claude Desktop, Claude Code, Cursor, Windsurf, ChatWise\n\n**Available Tools:** `execute_query`, `list_catalogs`, `list_schemas`, `list_tables`, `get_table_schema`, `explain_query`\n\nFor client integration and tool documentation, see [Integration Guide](docs/integrations.md) and [Tools Reference](docs/tools.md).\n\n## Configuration\n\n**Key Variables:** `TRINO_HOST`, `TRINO_USER`, `TRINO_SCHEME`, `MCP_TRANSPORT`, `OAUTH_PROVIDER`\n\n**Secret Management:** Inject secrets through the process environment — `mcp-trino` reads them directly. See [docs/secrets.md](docs/secrets.md) for 1Password, Vault, and Kubernetes recipes.\n\n```bash\n# 1Password (biometric-gated, zero disk writes)\nop run --env-file=.env -- mcp-trino\n\n# Vault (via vault-agent or CLI)\nTRINO_PASSWORD=$(vault kv get -field=password secret/mcp-trino) mcp-trino\n\n# Kubernetes: use standard Secret → envFrom in the Helm chart values\n```\n\n**OAuth Configuration:**\n\n```bash\n# Native mode (most secure - zero server-side secrets)\nexport OAUTH_ENABLED=true OAUTH_MODE=native OAUTH_PROVIDER=okta\nexport OIDC_ISSUER=https://company.okta.com OIDC_AUDIENCE=https://mcp-server.com\n\n# Proxy mode (centralized credential management)\nexport OAUTH_MODE=proxy OIDC_CLIENT_ID=app-id OIDC_CLIENT_SECRET=secret\nexport OAUTH_REDIRECT_URI=https://mcp-server.com/oauth/callback  # Fixed mode (localhost-only)\nexport OAUTH_REDIRECT_URI=https://app1.com/cb,https://app2.com/cb  # Allowlist mode\nexport JWT_SECRET=$(openssl rand -hex 32)  # Required for multi-pod deployments\n```\n\n**Performance Optimization:**\n\n```bash\n# Focus AI on specific schemas only (10-20x performance improvement)\nexport TRINO_ALLOWED_SCHEMAS=\"hive.analytics,hive.marts,hive.reporting\"\n```\n\n**User Identity Tracking:**\n\n```bash\n# Query Attribution is AUTOMATIC when OAuth is enabled\n# Queries are tagged with X-Trino-Client-Tags and X-Trino-Client-Info headers\n\n# For full impersonation (Trino enforces user permissions):\nexport TRINO_ENABLE_IMPERSONATION=true\nexport TRINO_IMPERSONATION_FIELD=email  # Options: username, email, subject\n```\n\nFor complete configuration, see [Deployment Guide](docs/deployment.md), [OAuth Guide](docs/oauth.md), [Allowlists Guide](docs/allowlists.md), and [User Identity Guide](docs/impersonation.md).\n\n## OAuth Implementation\n\nmcp-trino uses [oauth-mcp-proxy](https://github.com/tuannvm/oauth-mcp-proxy) - a standalone OAuth 2.1 library for Go MCP servers.\n\n**Why a separate library?**\n- ✅ Reusable across any Go MCP server\n- ✅ Independent testing and versioning\n- ✅ Dedicated documentation and examples\n- ✅ Community-maintained OAuth implementation\n\n**For OAuth details:**\n- [oauth-mcp-proxy Documentation](https://github.com/tuannvm/oauth-mcp-proxy#readme) - Complete OAuth guide\n- [Provider Setup Guides](https://github.com/tuannvm/oauth-mcp-proxy/tree/main/docs/providers) - Okta, Google, Azure AD\n- [Security Best Practices](https://github.com/tuannvm/oauth-mcp-proxy/blob/main/docs/SECURITY.md) - Production security\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Related Projects\n\n- **[oauth-mcp-proxy](https://github.com/tuannvm/oauth-mcp-proxy)** - OAuth 2.1 authentication library used by mcp-trino (reusable for any Go MCP server)\n\n## CI/CD and Releases\n\nThis project uses GitHub Actions for continuous integration and GoReleaser for automated releases.\n\n### Continuous Integration Checks\n\nOur CI pipeline performs the following checks on all PRs and commits to the main branch:\n\n#### Code Quality\n\n- **Linting**: Using golangci-lint to check for common code issues and style violations\n- **Go Module Verification**: Ensuring go.mod and go.sum are properly maintained\n- **Formatting**: Verifying code is properly formatted with gofmt\n\n#### Security\n\n- **Vulnerability Scanning**: Using govulncheck to check for known vulnerabilities in dependencies\n- **Dependency Scanning**: Using Trivy to scan for vulnerabilities in dependencies (CRITICAL, HIGH, and MEDIUM)\n- **SBOM Generation**: Creating a Software Bill of Materials for dependency tracking\n- **SLSA Provenance**: Creating verifiable build provenance for supply chain security\n\n#### Testing\n\n- **Unit Tests**: Running tests with race detection and code coverage reporting\n- **Build Verification**: Ensuring the codebase builds successfully\n\n#### CI/CD Security\n\n- **Least Privilege**: Workflows run with minimum required permissions\n- **Pinned Versions**: All GitHub Actions use specific versions to prevent supply chain attacks\n- **Dependency Updates**: Automated dependency updates via Dependabot\n\n### Release Process\n\nWhen changes are merged to the main branch:\n\n1. CI checks are run to validate code quality and security\n2. If successful, a new release is automatically created with:\n   - Semantic versioning based on commit messages\n   - Binary builds for multiple platforms\n   - Docker image publishing to GitHub Container Registry\n   - SBOM and provenance attestation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuannvm%2Fmcp-trino","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuannvm%2Fmcp-trino","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuannvm%2Fmcp-trino/lists"}