DBeaver MCP Server

Se integra con DBeaver para proporcionar a los asistentes de IA acceso a más de 200 tipos de bases de datos utilizando conexiones existentes.

GitHub
82
Prueba este MCPPatrocinado

Documentación

OmniSQL MCP

Servidor MCP universal de bases de datos: brinda a los asistentes de IA acceso de lectura/escritura a tus bases de datos utilizando conexiones ya guardadas en el espacio de trabajo de tu cliente de base de datos local (compatible con DBeaver).

npm version License: MIT Node.js

Soporte de bases de datos

Compatibilidad nativa (controlador directo, rápido):

  • PostgreSQL (a través de pg)
  • MySQL / MariaDB (a través de mysql2)
  • SQL Server / MSSQL (a través de mssql)
  • SQLite (a través de la CLI de sqlite3)

Compatible con Postgres (enrutado automáticamente a través del controlador pg):

  • CockroachDB, TimescaleDB, Amazon Redshift, YugabyteDB, AlloyDB, Supabase, Neon, Citus

Otras bases de datos: Se recurre a una CLI externa configurada mediante OMNISQL_CLI_PATH. Los resultados varían según la CLI.

Controladores personalizados que envuelven cualquiera de los anteriores se detectan automáticamente; consulta Controladores personalizados y autenticados con IAM.

Características

  • Reutiliza conexiones ya configuradas en el espacio de trabajo de tu cliente de base de datos local; sin configuración duplicada
  • Ejecución nativa de consultas para PostgreSQL, MySQL/MariaDB, SQLite, SQL Server
  • Autenticación IAM de AWS RDS, incluidos controladores personalizados basados en AWS Advanced JDBC Wrapper
  • Agrupación de conexiones con tamaño de grupo y tiempos de espera configurables
  • Soporte de transacciones (BEGIN/COMMIT/ROLLBACK)
  • Análisis del plan de ejecución de consultas (EXPLAIN)
  • Comparación de esquemas entre conexiones con generación de scripts de migración
  • Modo de solo lectura con SELECT obligatorio en execute_query
  • Lista blanca de conexiones para restringir qué bases de datos son accesibles
  • Filtrado de herramientas para deshabilitar operaciones específicas
  • Validación de consultas para bloquear operaciones peligrosas (DROP DATABASE, TRUNCATE, DELETE/UPDATE sin WHERE)
  • Exportación de datos a CSV/JSON
  • Apagado elegante con limpieza del grupo de conexiones

Requisitos

  • Node.js 18+
  • Un cliente de base de datos local (compatible con DBeaver) con al menos una conexión configurada

Instalación

npm install -g omnisql-mcp

Configuración

Claude Desktop

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Claude Code

Agrega a ~/.claude/settings.json:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Cursor

Agrega en Cursor Settings > MCP Servers:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Variables de entorno

VariableDescripciónPredeterminado
OMNISQL_CLI_PATHRuta a la CLI del cliente de base de datos externo (se usa para el respaldo de controladores no compatibles)Sin definir
OMNISQL_WORKSPACERuta al directorio del espacio de trabajo del cliente de base de datos localPredeterminado del sistema operativo
OMNISQL_PROJECTNombre de la carpeta del proyecto/espacio de trabajo del cliente de base de datos (p. ej., proyecto DBeaver con nombre personalizado)General
OMNISQL_TIMEOUTTiempo de espera de consulta (ms)30000
OMNISQL_DEBUGHabilitar registro de depuraciónfalse
OMNISQL_READ_ONLYDeshabilitar todas las operaciones de escriturafalse
OMNISQL_ALLOWED_CONNECTIONSLista blanca separada por comas de IDs o nombres de conexiónTodas
OMNISQL_DISABLED_TOOLSHerramientas separadas por comas para deshabilitarNinguna
OMNISQL_POOL_MINConexiones mínimas por grupo2
OMNISQL_POOL_MAXConexiones máximas por grupo10
OMNISQL_POOL_IDLE_TIMEOUTTiempo de espera de conexión inactiva (ms)30000
OMNISQL_POOL_ACQUIRE_TIMEOUTTiempo de espera de adquisición de conexión (ms)10000
OMNISQL_AWS_CLI_PATHRuta a la CLI de AWS (se usa para la autenticación IAM de RDS)aws
OMNISQL_IAM_TOKEN_TIMEOUTTiempo de espera para generar un token de autenticación IAM de RDS (ms)20000
OMNISQL_SSH_KNOWN_HOSTSArchivo known_hosts utilizado para verificar los hosts de túneles SSH~/.ssh/known_hosts
OMNISQL_SSH_STRICT_HOST_KEYRechazar hosts de túneles SSH sin entrada known_hostsfalse

Modo de solo lectura

Bloquea todas las operaciones de escritura. La herramienta execute_query solo permite sentencias SELECT, EXPLAIN, SHOW y DESCRIBE. Las herramientas de transacciones están completamente deshabilitadas.

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_READ_ONLY": "true"
      }
    }
  }
}

Lista blanca de conexiones

Restringe qué conexiones del espacio de trabajo son visibles. Acepta IDs de conexión o nombres para mostrar, separados por comas:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
      }
    }
  }
}

Deshabilitar herramientas específicas

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
      }
    }
  }
}

Herramientas disponibles

Gestión de conexiones

  • list_connections - Listar todas las conexiones de bases de datos
  • get_connection_info - Obtener detalles de la conexión
  • test_connection - Probar conectividad

Operaciones de datos

  • execute_query - Ejecutar consultas de solo lectura (solo SELECT, EXPLAIN, SHOW, DESCRIBE)
  • write_query - Ejecutar INSERT/UPDATE/DELETE
  • export_data - Exportar a CSV/JSON

Gestión de esquemas

  • list_tables - Listar tablas y vistas
  • get_table_schema - Obtener estructura de tabla
  • create_table - Crear tablas
  • alter_table - Modificar tablas
  • drop_table - Eliminar tablas (requiere confirmación)

Transacciones

  • begin_transaction - Iniciar una nueva transacción
  • execute_in_transaction - Ejecutar consulta dentro de una transacción
  • commit_transaction - Confirmar una transacción
  • rollback_transaction - Revertir una transacción

Análisis de consultas

  • explain_query - Analizar el plan de ejecución de consultas
  • compare_schemas - Comparar esquemas entre dos conexiones
  • get_pool_stats - Obtener estadísticas del grupo de conexiones

Otros

  • get_database_stats - Estadísticas de la base de datos
  • append_insight - Guardar notas de análisis
  • list_insights - Recuperar notas guardadas

Seguridad

  • Cumplimiento de solo lectura: execute_query solo acepta sentencias de solo lectura (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA). Las operaciones de escritura deben usar write_query.
  • Validación de consultas: Bloquea DROP DATABASE, DROP SCHEMA, TRUNCATE, DELETE/UPDATE sin WHERE, GRANT, REVOKE y sentencias de gestión de usuarios.
  • Lista blanca de conexiones: Restringe qué conexiones se exponen a través de OMNISQL_ALLOWED_CONNECTIONS.
  • Filtrado de herramientas: Deshabilita cualquier herramienta mediante OMNISQL_DISABLED_TOOLS.
  • Saneamiento de entradas: Los IDs de conexión e identificadores SQL se sanean para prevenir inyecciones.
  • Recomendación: Para uso en producción, también usa un usuario de solo lectura a nivel de base de datos para defensa en profundidad.

Soporte de formatos de espacio de trabajo

Admite ambos formatos de configuración escritos por clientes de base de datos compatibles con DBeaver:

  • Heredado: Configuración XML en .metadata/.plugins/org.jkiss.dbeaver.core/
  • Moderno: Configuración JSON en General/.dbeaver/

El nombre de la carpeta del proyecto/espacio de trabajo (General por defecto) es configurable mediante OMNISQL_PROJECT, por lo que los espacios de trabajo que usan un proyecto DBeaver personalizado o renombrado (p. ej., DataPlatform) se descubren sin necesidad de renombrar el proyecto ni crear un enlace simbólico a la carpeta.

Modos de conexión

Las conexiones de DBeaver se configuran manualmente (campos de host, puerto, base de datos) o por URL (una URL JDBC). Ambos funcionan. En modo URL, DBeaver deja los campos de host/puerto en valores de marcador de posición, generalmente localhost, y solo lee la URL, por lo que la URL es lo que se usa aquí también.

Túneles SSH

Las conexiones que DBeaver alcanza a través de un túnel SSH también se tunelizan aquí. El túnel se abre en el primer uso y se reutiliza durante toda la vida del servidor, con un reenvío local solo de bucle invertido, y el host/puerto de la conexión se tratan como DBeaver los trata: como la base de datos vista desde el servidor SSH.

  • Se admiten autenticación por agente, contraseña y clave pública, tomadas de la pestaña SSH de la conexión. Las credenciales guardadas en el espacio de trabajo (incluidas las del propio túnel, almacenadas por separado de las credenciales de la base de datos) se descifran y se usan.
  • La autenticación por agente necesita SSH_AUTH_SOCK configurado en el entorno del servidor MCP. Los clientes MCP generalmente no heredan tu shell, así que configúralo explícitamente en la configuración del servidor del cliente si usas un agente.
  • La clave de host SSH se verifica contra known_hosts. Un host registrado allí debe coincidir, o el túnel se rechaza; un host que no está registrado se acepta, a menos que OMNISQL_SSH_STRICT_HOST_KEY=true.
  • Si no se puede abrir un túnel, la conexión falla con ese motivo. Nunca recurre a conectarse directamente al host registrado, lo que alcanzaría una base de datos local no relacionada.

Consultar otra base de datos en el mismo servidor

Un ID de conexión puede llevar una anulación de base de datos — my-connection/analytics — para ejecutar contra una base de datos diferente en el mismo servidor sin agregar una segunda conexión en DBeaver. Esto no aplica a motores respaldados por archivos como SQLite, donde la "base de datos" es una ruta de archivo.

Con OMNISQL_ALLOWED_CONNECTIONS configurado, incluir en la lista blanca una conexión permite las bases de datos que sus credenciales pueden alcanzar. Para fijarla a bases de datos específicas, lista entradas connection/database en lugar de la conexión simple.

Las credenciales se descifran automáticamente desde el credentials-config.json del espacio de trabajo.

Controladores personalizados y autenticados con IAM

Controladores personalizados

El enrutamiento nativo normalmente se basa en el ID del controlador (postgres-jdbc, mysql8). Los controladores personalizados a menudo usan un ID opaco en su lugar — un UUID, por ejemplo — que no nombra ningún motor. Esas conexiones se resuelven recurriendo al provider de la conexión (postgresql, mysql, …) y luego al subprotocolo de la URL JDBC, incluidos los envueltos como jdbc:aws-wrapper:postgresql://…. Por lo tanto, un controlador personalizado que envuelve un motor compatible funciona sin configuración adicional.

Si aún no se puede identificar un motor, el error resultante nombra tanto el ID del controlador como el proveedor para que puedas ver qué faltaba.

Autenticación IAM de AWS RDS

Las conexiones que se autentican con un token IAM de RDS en lugar de una contraseña almacenada se detectan y manejan automáticamente. Se reconocen ambas formas:

  • Controladores AWS Advanced JDBC Wrapper, que registran wrapperPlugins: "iam" junto con awsProfile y iamRegion.
  • Los modelos de autenticación IAM de AWS propios del cliente de base de datos.

Para estas conexiones, OmniSQL:

  1. Genera un token con aws rds generate-db-auth-token (a través de la CLI de AWS, por lo que los perfiles SSO y de roles encadenados funcionan según lo configurado) y lo usa como contraseña.
  2. Almacena en caché cada token durante 13 minutos, dentro de su vida útil de 15 minutos, y lo regenera por conexión física para que los grupos de larga duración sigan funcionando.
  3. Fuerza TLS, que RDS requiere para tokens IAM.
  4. Resuelve el nombre de usuario de la base de datos desde la conexión cuando está presente. Cuando está ausente, el nombre de usuario se deriva de tu identidad de AWS: ya sea el nombre del rol por desarrollador (<profile>-<user>) o el nombre de sesión SSO asumido.

Requisitos: la CLI de AWS en PATH (o OMNISQL_AWS_CLI_PATH), una sesión válida para el perfil de la conexión (aws sso login --profile <profile>) y accesibilidad de red al endpoint. Una sesión SSO caducada produce un error que nombra el perfil para reautenticar.

Desarrollo

git clone https://github.com/srthkdev/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build
npm test
npm run lint

Licencia

MIT