MCP Trino Server

MCP Trino Server

O MCP Trino Server é um servidor Model Context Protocol (MCP) que fornece integração perfeita com Trino e Iceberg, permitindo exploração avançada de dados, consultas e capacidades de manutenção de tabelas por meio de uma interface padrão.

Casos de Uso

• Exploração e análise interativa de dados no Trino
• Manutenção e otimização automatizada de tabelas Iceberg
• Criação de ferramentas baseadas em IA que interagem com bancos de dados Trino
• Execução e gerenciamento de consultas SQL com formatação adequada de resultados

Pré-requisitos

1. Um servidor Trino em execução (ou Docker Compose para desenvolvimento local)
2. Python 3.12 ou superior
3. Docker (opcional, para implantação em contêiner)

Início Rápido

1. Clonar o Repositório

git clone https://github.com/alaturqua/mcp-trino-python.git
cd mcp-trino-python

2. Criar Arquivo de Ambiente

Crie um arquivo .env no diretório raiz:

TRINO_HOST=localhost
TRINO_PORT=8080
TRINO_USER=trino
TRINO_CATALOG=tpch
TRINO_SCHEMA=tiny

3. Executar Trino Localmente (Opcional)

docker-compose up -d trino

Isso inicia um servidor Trino em localhost:8080 com dados de exemplo TPC-H e TPC-DS.

Instalação

Instalação via Smithery

Para instalar o MCP Trino Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @alaturqua/mcp-trino-python --client claude

Usando uv (Recomendado)

uv sync
uv run src/server.py

Usando pip

pip install -e .
python src/server.py

Modos de Transporte

O servidor suporta três modos de transporte:

Transporte	Descrição	Caso de Uso
stdio	Entrada/Saída padrão (padrão)	VS Code, Claude Desktop, clientes MCP locais
streamable-http	HTTP com streaming	Acesso remoto, clientes web, Docker
sse	Server-Sent Events	Transporte HTTP legado

Executando com Diferentes Transportes

# stdio (default) - for VS Code and Claude Desktop
python src/server.py

# Streamable HTTP - for remote/web access
python src/server.py --transport streamable-http --host 0.0.0.0 --port 8000

# SSE - legacy HTTP transport
python src/server.py --transport sse --host 0.0.0.0 --port 8000

Uso com VS Code

Adicione às configurações do seu VS Code (Ctrl+Shift+P → Preferences: Open User Settings (JSON)):

{
  "mcp": {
    "servers": {
      "mcp-trino-python": {
        "command": "uv",
        "args": [
          "run",
          "--with",
          "mcp[cli]",
          "--with",
          "trino",
          "--with",
          "loguru",
          "mcp",
          "run",
          "/path/to/mcp-trino-python/src/server.py"
        ],
        "envFile": "/path/to/mcp-trino-python/.env"
      }
    }
  }
}

Ou adicione a .vscode/mcp.json no seu workspace (sem a chave de wrapper mcp).

Uso com Claude Desktop

Adicione à configuração do seu Claude Desktop:

{
  "mcpServers": {
    "trino": {
      "command": "python",
      "args": ["./src/server.py"],
      "env": {
        "TRINO_HOST": "your-trino-host",
        "TRINO_PORT": "8080",
        "TRINO_USER": "trino"
      }
    }
  }
}

Uso com Docker

Construir a Imagem

docker build -t mcp-trino-python .

Executar com stdio (para VS Code)

docker run -i --rm \
  -e TRINO_HOST=host.docker.internal \
  -e TRINO_PORT=8080 \
  -e TRINO_USER=trino \
  mcp-trino-python

Executar com HTTP Streamable

docker run -p 8000:8000 \
  -e TRINO_HOST=host.docker.internal \
  -e TRINO_PORT=8080 \
  mcp-trino-python \
  --transport streamable-http --host 0.0.0.0 --port 8000

Docker Compose

# Start Trino + MCP server with Streamable HTTP
docker-compose up -d

# Start with SSE transport
docker-compose --profile sse up -d

# Run stdio for testing
docker-compose --profile stdio run --rm mcp-trino-stdio

VS Code com Docker

{
  "mcp": {
    "servers": {
      "mcp-trino-python": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "--network",
          "mcp-trino-python_trino-network",
          "-e",
          "TRINO_HOST=trino",
          "-e",
          "TRINO_PORT=8080",
          "-e",
          "TRINO_USER=trino",
          "mcp-trino-python"
        ]
      }
    }
  }
}

Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
TRINO_HOST	Nome do host do servidor Trino	localhost
TRINO_PORT	Porta do servidor Trino	8080
TRINO_USER	Nome de usuário do Trino	trino
TRINO_CATALOG	Catálogo padrão	None
TRINO_SCHEMA	Esquema padrão	None
TRINO_HTTP_SCHEME	Esquema HTTP (http/https)	http
TRINO_PASSWORD	Senha do Trino	None

Ferramentas

Ferramentas de Consulta e Exploração

• show_catalogs

  • Lista todos os catálogos disponíveis
  • Nenhum parâmetro necessário

• show_schemas

  • Lista todos os esquemas em um catálogo
  • Parâmetros:
    • catalog: Nome do catálogo (string, obrigatório)

• show_tables

  • Lista todas as tabelas em um esquema
  • Parâmetros:
    • catalog: Nome do catálogo (string, obrigatório)
    • schema: Nome do esquema (string, obrigatório)

• describe_table

  • Mostra estrutura detalhada da tabela e informações das colunas
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• execute_query

  • Executa uma consulta SQL e retorna resultados formatados
  • Parâmetros:
    • query: Consulta SQL a executar (string, obrigatório)

• show_catalog_tree

  • Mostra uma visão hierárquica em árvore de catálogos, esquemas e tabelas
  • Retorna uma estrutura de árvore formatada com indicadores visuais
  • Nenhum parâmetro necessário

• show_create_table

  • Mostra a instrução CREATE TABLE para uma tabela
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_create_view

  • Mostra a instrução CREATE VIEW para uma visão
  • Parâmetros:
    • view: Nome da visão (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_stats

  • Mostra estatísticas para uma tabela
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

Manutenção de Tabelas Iceberg

• optimize

  • Otimiza uma tabela Iceberg compactando arquivos pequenos
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• optimize_manifests

  • Otimiza arquivos de manifesto para uma tabela Iceberg
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• expire_snapshots

  • Remove snapshots antigos de uma tabela Iceberg
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • retention_threshold: Limite de idade (ex.: "7d") (string, opcional)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

Inspeção de Metadados Iceberg

• show_table_properties

  • Mostra propriedades da tabela Iceberg
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_table_history

  • Mostra histórico/registro de alterações da tabela Iceberg
  • Contém informações de tempo de snapshot, linhagem e ancestralidade
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_metadata_log_entries

  • Mostra entradas de log de metadados da tabela Iceberg
  • Contém locais de arquivos de metadados e informações de sequência
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_snapshots

  • Mostra snapshots da tabela Iceberg
  • Contém detalhes de snapshot, incluindo operações e arquivos de manifesto
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_manifests

  • Mostra manifestos da tabela Iceberg para snapshots atuais ou todos
  • Contém detalhes de arquivos de manifesto e estatísticas de arquivos de dados
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)
    • all_snapshots: Incluir todos os snapshots (booleano, opcional)

• show_partitions

  • Mostra partições da tabela Iceberg
  • Contém estatísticas de partição e contagens de arquivos
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_files

  • Mostra arquivos de dados da tabela Iceberg no snapshot atual
  • Contém metadados detalhados de arquivos e estatísticas de colunas
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

• show_entries

  • Mostra entradas de manifesto da tabela Iceberg para snapshots atuais ou todos
  • Contém status de entrada e métricas detalhadas de arquivos
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)
    • all_snapshots: Incluir todos os snapshots (booleano, opcional)

• show_refs

  • Mostra referências da tabela Iceberg (branches e tags)
  • Contém configuração de referência e mapeamento de snapshot
  • Parâmetros:
    • table: Nome da tabela (string, obrigatório)
    • catalog: Nome do catálogo (string, opcional)
    • schema: Nome do esquema (string, opcional)

Histórico de Consultas

• show_query_history
  • Obtém o histórico de consultas executadas
  • Parâmetros:
    • limit: Número máximo de consultas a retornar (número, opcional)

Licença

Este projeto é licenciado sob a Licença Apache 2.0. Consulte o arquivo LICENSE para os termos completos.