Vertica MCP Server

Proporciona acceso de solo lectura a bases de datos Vertica.

GitHub
8
Prueba este MCPPatrocinado

Documentación

Vertica MCP Server

Un servidor de Model Context Protocol (MCP) para bases de datos Vertica. Permite a los asistentes de IA consultar y explorar bases de datos Vertica mediante lenguaje natural.

Diseño con seguridad primero: Modo de solo lectura por defecto. Las operaciones de escritura requieren configuración explícita.

Características

  • 6 herramientas MCP: Ejecución de consultas, streaming, descubrimiento de esquema
  • Protección de solo lectura: Solo consultas SELECT/SHOW/DESCRIBE/EXPLAIN/WITH por defecto
  • Streaming de grandes conjuntos de datos: Procesamiento por lotes eficiente (hasta 1M de filas)
  • Optimizado para Vertica: Conocimiento de proyecciones, soporte de consultas columnar
  • Listo para producción: Pool de conexiones, soporte SSL, configuración de tiempo de espera
  • Enlace de parámetros: Protección contra inyección SQL
  • Conexión persistente: Reutiliza una única conexión con tiempo de espera de inactividad configurable
  • Balanceo de carga: Redirección opcional al nodo Vertica óptimo al conectar

Inicio rápido

Claude Code

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

Crea tu archivo .env con los detalles de conexión:

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

Cursor

  1. Crea el archivo de entorno ~/.cursor/vertica.env:
VERTICA_HOST=your-vertica-host.com
VERTICA_PORT=5433
VERTICA_DATABASE=your_database
VERTICA_USER=your_username
VERTICA_PASSWORD=your_password
  1. Configura ~/.cursor/mcp.json:
{
  "mcpServers": {
    "vertica-mcp": {
      "command": "npx",
      "args": [
        "@hechtcarmel/vertica-mcp",
        "--env-file",
        "/Users/yourusername/.cursor/vertica.env"
      ]
    }
  }
}
  1. Reinicia 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"
      ]
    }
  }
}

Configuración

Variables requeridas

VERTICA_HOST          # Database hostname
VERTICA_DATABASE      # Database name
VERTICA_USER          # Username

Variables opcionales

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

Habilitar operaciones de escritura

Para permitir operaciones INSERT/UPDATE/DELETE/CREATE/DROP:

VERTICA_READONLY_MODE=false

Advertencia: Solo desactiva el modo de solo lectura si entiendes las implicaciones.

Conexión persistente y tiempo de espera de inactividad

El servidor reutiliza una única conexión entre llamadas a herramientas. Si permanece inactivo durante más de VERTICA_IDLE_TIMEOUT, se desconecta automáticamente y se reconecta en el siguiente uso.

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

Balanceo de carga de conexión

Cuando está habilitado, el servidor consulta DESCRIBE_LOAD_BALANCE_DECISION de Vertica en la primera conexión y se reconecta de forma transparente al nodo óptimo si hay una redirección disponible, replicando el comportamiento de los controladores JDBC/ODBC de Vertica.

VERTICA_CONNECTION_LOAD_BALANCE=true

Nota: Requiere que la IP de redirección sea accesible desde el host del servidor MCP.

Herramientas disponibles

Ejecución de consultas

  • execute_query: Ejecuta SQL con parámetros opcionales
  • stream_query: Maneja grandes conjuntos de datos con lotes configurables

Descubrimiento de esquema

  • get_table_structure: Columnas de tabla, tipos, restricciones
  • list_tables: Todas las tablas en el esquema con metadatos
  • list_views: Todas las vistas con definiciones
  • list_indexes: Proyecciones de Vertica para optimización

Ejemplos de uso

Consultar datos

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;

Analizar rendimiento

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

Transmitir resultados grandes

Al consultar grandes conjuntos de datos, usa la herramienta stream_query:

  • Tamaño de lote predeterminado: 1000 filas
  • Tamaño de lote configurable: 1-10,000 filas
  • Máximo de filas: 1,000,000

Solución de problemas

Fallo de conexión

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

Verifica:

  • Que el host y el puerto sean accesibles
  • Que las credenciales de la base de datos sean correctas
  • Que el usuario tenga los permisos necesarios

Errores de permisos

  • El usuario necesita permisos SELECT en las tablas
  • El usuario necesita acceso a los catálogos del sistema (v_catalog.*)

Tiempos de espera de consulta

Aumenta el tiempo de espera para consultas complejas:

VERTICA_QUERY_TIMEOUT=300000  # 5 minutes

Conjuntos de resultados grandes

Usa stream_query en lugar de execute_query para consultas que devuelvan más de 10,000 filas.

Fallo de redirección de balanceo de carga

Si VERTICA_CONNECTION_LOAD_BALANCE=true pero el enrutamiento falla, el servidor registra una advertencia y permanece en el host inicial; no se devuelve ningún error al cliente. Verifica que todos los nodos del clúster de Vertica sean accesibles desde el servidor MCP.

Requisitos

  • Node.js >= 18.0.0
  • Base de datos Vertica (cualquier versión reciente)
  • Acceso de red al servidor Vertica

Soporte

Licencia

Licencia MIT - consulta el archivo LICENSE.

Agradecimientos

La arquitectura y el diseño de herramientas de este proyecto se basan en mcp-vertica de @nolleh.

Versión actual: 1.4.0