276 lines
6.2 KiB
Markdown
276 lines
6.2 KiB
Markdown
# Claude Code Integration (MCP)
|
|
|
|
Claude Code can query Trino directly using the [mcp-trino](https://github.com/tuannvm/mcp-trino) MCP server.
|
|
|
|
## Installation
|
|
|
|
### 1. Install mcp-trino
|
|
|
|
```bash
|
|
brew install tuannvm/mcp/mcp-trino
|
|
```
|
|
|
|
### 2. Add to Claude Code Global Configuration
|
|
|
|
```bash
|
|
claude mcp add --scope user mcp-trino mcp-trino
|
|
```
|
|
|
|
This creates a global MCP server configuration at `~/.claude.json`. The `env: {}` configuration means environment variables will be inherited from the parent process.
|
|
|
|
## Basic Configuration
|
|
|
|
### 1. Create `.env.claude`
|
|
|
|
Create `.env.claude` with Trino connection settings:
|
|
|
|
```bash
|
|
# Trino Connection (Password Authentication)
|
|
TRINO_HOST=trino.yourdomain.com
|
|
TRINO_PORT=443
|
|
TRINO_SCHEME=https
|
|
TRINO_SSL=true
|
|
TRINO_SSL_INSECURE=true
|
|
TRINO_USER=admin
|
|
TRINO_PASSWORD="your-password-here" # Direct password
|
|
TRINO_CATALOG=iceberg
|
|
TRINO_SCHEMA=default
|
|
|
|
# Performance: Limit schemas to improve query performance
|
|
TRINO_ALLOWED_CATALOGS=iceberg,tpch,postgresql
|
|
TRINO_ALLOWED_SCHEMAS=iceberg.ecommerce_marts,iceberg.analytics,tpch.sf1
|
|
|
|
# Query Configuration
|
|
TRINO_ALLOW_WRITE_QUERIES=false
|
|
TRINO_QUERY_TIMEOUT=30s
|
|
|
|
# MCP Transport (STDIO mode)
|
|
MCP_TRANSPORT=stdio
|
|
|
|
# OAuth (disabled for Trino connection - using password auth instead)
|
|
OAUTH_ENABLED=false
|
|
```
|
|
|
|
Get the admin password:
|
|
|
|
```bash
|
|
just trino::admin-password
|
|
```
|
|
|
|
### 2. Start Claude Code
|
|
|
|
Load environment variables and start Claude Code:
|
|
|
|
```bash
|
|
source .env.claude && claude
|
|
```
|
|
|
|
## 1Password Integration
|
|
|
|
For better security, store credentials in 1Password and inject them at runtime.
|
|
|
|
### 1. Create `~/.env.claude`
|
|
|
|
Create `~/.env.claude` in your home directory with 1Password references:
|
|
|
|
```bash
|
|
# Trino Connection (Password Authentication)
|
|
TRINO_HOST=trino.yourdomain.com
|
|
TRINO_PORT=443
|
|
TRINO_SCHEME=https
|
|
TRINO_SSL=true
|
|
TRINO_SSL_INSECURE=true
|
|
TRINO_USER=admin
|
|
TRINO_PASSWORD="op://Personal/trino/password" # 1Password reference
|
|
TRINO_CATALOG=iceberg
|
|
TRINO_SCHEMA=default
|
|
|
|
# Performance: Limit schemas to improve query performance
|
|
TRINO_ALLOWED_CATALOGS=iceberg,tpch,postgresql
|
|
TRINO_ALLOWED_SCHEMAS=iceberg.ecommerce_marts,iceberg.analytics,tpch.sf1
|
|
|
|
# Query Configuration
|
|
TRINO_ALLOW_WRITE_QUERIES=false
|
|
TRINO_QUERY_TIMEOUT=30s
|
|
|
|
# MCP Transport (STDIO mode)
|
|
MCP_TRANSPORT=stdio
|
|
|
|
# OAuth (disabled for Trino connection - using password auth instead)
|
|
OAUTH_ENABLED=false
|
|
```
|
|
|
|
### 2. Create Shell Script
|
|
|
|
Create a shell script to inject secrets and start Claude Code (e.g., `~/bin/claude-op`):
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
set -euo pipefail
|
|
set -a
|
|
eval "$(op inject -i ~/.env.claude)"
|
|
set +a
|
|
claude
|
|
```
|
|
|
|
Make it executable:
|
|
|
|
```bash
|
|
chmod +x ~/bin/claude-op
|
|
```
|
|
|
|
### 3. Start Claude Code
|
|
|
|
```bash
|
|
claude-op
|
|
```
|
|
|
|
This command:
|
|
|
|
1. Injects secrets from 1Password using `op inject`
|
|
2. Exports environment variables to the shell
|
|
3. Starts Claude Code with environment variables inherited by mcp-trino
|
|
|
|
## Usage
|
|
|
|
Once configured, Claude Code can interact with Trino using natural language:
|
|
|
|
**Examples:**
|
|
|
|
```plain
|
|
Show me all tables in the ecommerce_marts schema
|
|
```
|
|
|
|
```plain
|
|
What's the schema of the dim_products table?
|
|
```
|
|
|
|
```plain
|
|
Query the top 10 products by revenue
|
|
```
|
|
|
|
## Available MCP Tools
|
|
|
|
The mcp-trino server provides the following tools:
|
|
|
|
- **`list_catalogs`**: List all available Trino catalogs
|
|
- **`list_schemas`**: List schemas in a catalog
|
|
- **`list_tables`**: List tables in a schema
|
|
- **`get_table_schema`**: Get column definitions and types for a table
|
|
- **`execute_query`**: Execute SELECT queries
|
|
- **`explain_query`**: Show query execution plan
|
|
|
|
## Configuration Options
|
|
|
|
### Performance Tuning
|
|
|
|
**`TRINO_ALLOWED_CATALOGS`** and **`TRINO_ALLOWED_SCHEMAS`**:
|
|
|
|
- Limits which catalogs and schemas are accessible
|
|
- Improves performance by reducing metadata queries
|
|
- Reduces attack surface
|
|
|
|
**`TRINO_QUERY_TIMEOUT`**:
|
|
|
|
- Maximum time allowed for query execution
|
|
- Prevents long-running queries from consuming resources
|
|
|
|
### Security Settings
|
|
|
|
**`TRINO_ALLOW_WRITE_QUERIES`**:
|
|
|
|
- Set to `false` to prevent INSERT, UPDATE, DELETE, CREATE, DROP statements
|
|
- Recommended for read-only data exploration
|
|
|
|
**`TRINO_SSL_INSECURE`**:
|
|
|
|
- Set to `true` to allow self-signed certificates
|
|
- Required for development environments with self-signed certs
|
|
- Should be `false` in production with valid certificates
|
|
|
|
## Troubleshooting
|
|
|
|
### MCP Server Not Connecting
|
|
|
|
Check the MCP server status:
|
|
|
|
```bash
|
|
claude mcp list
|
|
```
|
|
|
|
You should see:
|
|
|
|
```plain
|
|
mcp-trino: mcp-trino - ✓ Connected
|
|
```
|
|
|
|
If it shows `✗ Failed to connect`, check:
|
|
|
|
1. **Environment variables are set**: Verify `.env.claude` exists and contains all required variables
|
|
2. **Trino is accessible**: Test with `curl -k https://${TRINO_HOST}`
|
|
3. **1Password CLI is authenticated** (if using 1Password): Run `op whoami` to check
|
|
|
|
### Authentication Fails
|
|
|
|
If queries fail with authentication errors:
|
|
|
|
1. **Verify password**: Get the correct password with `just trino::admin-password`
|
|
2. **Check environment variable**: Ensure `TRINO_PASSWORD` is set correctly
|
|
3. **Test manually**:
|
|
|
|
```bash
|
|
source .env.claude
|
|
echo $TRINO_PASSWORD # Verify password is loaded
|
|
```
|
|
|
|
For 1Password users:
|
|
|
|
```bash
|
|
source <(op inject -i ~/.env.claude)
|
|
echo $TRINO_PASSWORD # Verify password injection worked
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Basic Configuration
|
|
|
|
```plain
|
|
User
|
|
↓
|
|
source .env.claude && claude
|
|
↓ (loads environment variables)
|
|
Claude Code (inherits env vars)
|
|
↓ (STDIO transport)
|
|
mcp-trino (reads env vars)
|
|
↓ (HTTPS with password auth)
|
|
Trino Server
|
|
```
|
|
|
|
### Advanced: 1Password Integration
|
|
|
|
```plain
|
|
User
|
|
↓
|
|
claude-op (shell script)
|
|
↓ (op inject from ~/.env.claude)
|
|
Claude Code (inherits env vars)
|
|
↓ (STDIO transport)
|
|
mcp-trino (reads env vars)
|
|
↓ (HTTPS with password auth)
|
|
Trino Server
|
|
```
|
|
|
|
**Key Points:**
|
|
|
|
- mcp-trino runs as a child process of Claude Code
|
|
- Environment variables flow from shell → Claude Code → mcp-trino
|
|
- No configuration file needed for mcp-trino; all settings via environment variables
|
|
- 1Password injection happens once at startup (Advanced), not per-query
|
|
|
|
## References
|
|
|
|
- [mcp-trino GitHub Repository](https://github.com/tuannvm/mcp-trino)
|
|
- [Claude Code MCP Documentation](https://docs.claude.com/en/docs/claude-code/mcp)
|
|
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
|
|
- [1Password CLI Documentation](https://developer.1password.com/docs/cli/)
|