Vertica MCP Server

Fornece acesso somente leitura a bancos de dados Vertica.

Documentação

Servidor MCP Vertica

Um servidor Model Context Protocol (MCP) para bancos de dados Vertica. Permite que assistentes de IA consultem e explorem bancos de dados Vertica por meio de linguagem natural.

Design com foco em segurança: Modo somente leitura por padrão. Operações de escrita exigem configuração explícita.

Recursos

6 Ferramentas MCP: Execução de consultas, streaming, descoberta de esquema
Proteção somente leitura: Apenas consultas SELECT/SHOW/DESCRIBE/EXPLAIN/WITH por padrão
Streaming de grandes conjuntos de dados: Processamento eficiente em lote (até 1 milhão de linhas)
Otimizado para Vertica: Consciência de projeção, suporte a consultas colunares
Pronto para produção: Pool de conexões, suporte SSL, configuração de timeout
Vinculação de parâmetros: Proteção contra injeção de SQL
Conexão persistente: Reutiliza uma única conexão com timeout de inatividade configurável
Balanceamento de carga: Redirecionamento opcional para o nó Vertica ideal na conexão

Início Rápido

Claude Code

claude mcp add vertica --scope user -- npx -y @hechtcarmel/vertica-mcp@latest  --env-file /path/to/your/.env

Crie seu arquivo .env com os detalhes de conexão:

VERTICA_HOST=your-vertica-host.com
VERTICA_PORT=5433
VERTICA_DATABASE=your_database
VERTICA_USER=your_username
VERTICA_PASSWORD=your_password

Cursor

Crie o arquivo de ambiente ~/.cursor/vertica.env:

VERTICA_HOST=your-vertica-host.com
VERTICA_PORT=5433
VERTICA_DATABASE=your_database
VERTICA_USER=your_username
VERTICA_PASSWORD=your_password

Configure ~/.cursor/mcp.json:

{
  "mcpServers": {
    "vertica-mcp": {
      "command": "npx",
      "args": [
        "@hechtcarmel/vertica-mcp",
        "--env-file",
        "/Users/yourusername/.cursor/vertica.env"
      ]
    }
  }
}

Reinicie o Cursor

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vertica-mcp": {
      "command": "npx",
      "args": [
        "@hechtcarmel/vertica-mcp",
        "--env-file",
        "/path/to/your/.env"
      ]
    }
  }
}

Configuração

Variáveis Obrigatórias

VERTICA_HOST          # Database hostname
VERTICA_DATABASE      # Database name
VERTICA_USER          # Username

Variáveis Opcionais

VERTICA_PORT=5433                      # Default: 5433
VERTICA_PASSWORD                       # Password (optional)
VERTICA_READONLY_MODE=true             # Default: true
VERTICA_QUERY_TIMEOUT=60000            # Default: 60000ms
VERTICA_IDLE_TIMEOUT=3600000           # Default: 3600000ms (1h), range: 60s-24h
VERTICA_SSL=false                      # Default: false
VERTICA_SSL_REJECT_UNAUTHORIZED=true   # Default: true
VERTICA_DEFAULT_SCHEMA=public          # Default: public
VERTICA_CONNECTION_LOAD_BALANCE=false  # Default: false

Habilitando Operações de Escrita

Para permitir operações INSERT/UPDATE/DELETE/CREATE/DROP:

VERTICA_READONLY_MODE=false

Aviso: Somente desative o modo somente leitura se você entender as implicações.

Conexão Persistente e Timeout de Inatividade

O servidor reutiliza uma única conexão entre chamadas de ferramentas. Se ficar inativo por mais de VERTICA_IDLE_TIMEOUT, ele desconecta automaticamente e reconecta no próximo uso.

VERTICA_IDLE_TIMEOUT=3600000  # 1 hour (default), min: 60000ms, max: 86400000ms

Balanceamento de Carga de Conexão

Quando habilitado, o servidor consulta o DESCRIBE_LOAD_BALANCE_DECISION do Vertica na primeira conexão e reconecta de forma transparente ao nó ideal se um redirecionamento estiver disponível, correspondendo ao comportamento dos drivers JDBC/ODBC do Vertica.

VERTICA_CONNECTION_LOAD_BALANCE=true

Nota: Requer que o IP de redirecionamento seja acessível a partir do host do servidor MCP.

Ferramentas Disponíveis

Execução de Consultas

execute_query: Executa SQL com parâmetros opcionais
stream_query: Lida com grandes conjuntos de dados com processamento em lote configurável

Descoberta de Esquema

get_table_structure: Colunas, tipos e restrições de tabelas
list_tables: Todas as tabelas no esquema com metadados
list_views: Todas as views com definições
list_indexes: Projeções do Vertica para otimização

Exemplos de Uso

Consultar Dados

SELECT customer_state, COUNT(*) as count
FROM customer_dimension
GROUP BY customer_state
ORDER BY count DESC
LIMIT 10;

Explorar Esquema

SHOW TABLES;
DESCRIBE customer_dimension;

Analisar Desempenho

EXPLAIN SELECT * FROM store_sales_fact
WHERE sale_date_key > '2023-01-01';

Transmitir Grandes Resultados

Ao consultar grandes conjuntos de dados, use a ferramenta stream_query:

Tamanho padrão do lote: 1000 linhas
Tamanho configurável do lote: 1-10.000 linhas
Máximo de linhas: 1.000.000

Solução de Problemas

Falha na Conexão

# Test connectivity directly
vsql -h localhost -p 5433 -d VMart -U dbadmin

Verifique:

Se o host e a porta estão acessíveis
Se as credenciais do banco de dados estão corretas
Se o usuário tem as permissões necessárias

Erros de Permissão

O usuário precisa de permissões SELECT nas tabelas
O usuário precisa de acesso aos catálogos do sistema (v_catalog.*)

Timeouts de Consulta

Aumente o timeout para consultas complexas:

VERTICA_QUERY_TIMEOUT=300000  # 5 minutes

Grandes Conjuntos de Resultados

Use stream_query em vez de execute_query para consultas que retornam mais de 10.000 linhas.

Falha no Redirecionamento de Balanceamento de Carga

Se VERTICA_CONNECTION_LOAD_BALANCE=true mas o roteamento falhar, o servidor registra um aviso e permanece no host inicial - nenhum erro é retornado ao cliente. Verifique se todos os nós do cluster Vertica estão acessíveis a partir do servidor MCP.

Requisitos

Node.js >= 18.0.0
Banco de dados Vertica (qualquer versão recente)
Acesso de rede ao servidor Vertica

Suporte

Problemas: GitHub Issues
Versões: GitHub Releases

Licença

Licença MIT - consulte o arquivo LICENSE.

Agradecimentos

A arquitetura deste projeto e o design das ferramentas são baseados em mcp-vertica por @nolleh.

Versão Atual: 1.4.0