OmniSQL MCP

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

Esto es un fork de srthkdev/omnisql-mcp que añade soporte de túnel SSH / host de salto. No está publicado en npm — compílalo desde este repositorio (consulta Instalación).

Soporte de bases de datos

Compatible de forma nativa (controlador directo, rápido):

• PostgreSQL (mediante pg)

• MySQL / MariaDB (mediante mysql2)

• SQL Server / MSSQL (mediante mssql)

• SQLite (mediante la CLI sqlite3)

• Trino / Presto (mediante trino-client)

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: recurre a una CLI externa configurada mediante OMNISQL_CLI_PATH. Los resultados varían según la CLI.

Related MCP server: DBHub

Características

• Reutiliza las conexiones ya configuradas en el espacio de trabajo de tu cliente de BD local: no hay que configurarlas de nuevo.

• Soporte automático de túnel SSH / host de salto: se conecta de forma transparente a través del mismo túnel SSH y perfil de puerta de enlace/host de salto configurado en la conexión (incluidos servidores de salto encadenados), sin necesidad de configurar un túnel aparte.

• Ejecución nativa de consultas para PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Trino/Presto.

• Pool de conexiones con tamaño y tiempos de espera configurables (el pooling no se aplica a SQLite ni a Trino/Presto, que no mantienen conexión por consulta).

• 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 restricción de solo SELECT 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 ordenado con limpieza del pool de conexiones.

Requisitos

• Node.js 18+

• Un cliente de BD local (compatible con DBeaver) con al menos una conexión configurada.

Instalación

Este fork no está publicado en npm: compílalo desde el código fuente:

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

Luego enlaza el servidor compilado para que el comando omnisql-mcp apunte a él:

npm install -g .

No ejecutes npm install -g omnisql-mcp por sí solo. Eso instala el paquete original upstream desde el registro de npm, que no tiene soporte de túnel SSH / host de salto. Debes clonar este repositorio y compilarlo localmente, y luego ejecutar npm install -g . desde dentro de la carpeta clonada como se muestra arriba.

Configuración

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Claude Code

Añade a ~/.claude/settings.json:

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

Cursor

Añade en Configuración de Cursor > Servidores MCP:

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

Sin instalación global

Si prefieres no ejecutar npm install -g ., apunta tu cliente MCP directamente al punto de entrada compilado:

{
  "mcpServers": {
    "omnisql": {
      "command": "node",
      "args": ["/absolute/path/to/omnisql-mcp/dist/index.js"]
    }
  }
}

Variables de entorno

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 - Lista todas las conexiones de bases de datos

• get_connection_info - Obtiene los detalles de la conexión

• test_connection - Prueba la conectividad

Operaciones de datos

• execute_query - Ejecuta consultas de solo lectura (solo SELECT, EXPLAIN, SHOW, DESCRIBE)

• write_query - Ejecuta INSERT/UPDATE/DELETE

• export_data - Exporta a CSV/JSON

Gestión de esquemas

• list_tables - Lista tablas y vistas

• get_table_schema - Obtiene la estructura de la tabla

• create_table - Crea tablas

• alter_table - Modifica tablas

• drop_table - Elimina tablas (requiere confirmación)

Transacciones

• begin_transaction - Inicia una nueva transacción

• execute_in_transaction - Ejecuta una consulta dentro de una transacción

• commit_transaction - Confirma una transacción

• rollback_transaction - Revierte una transacción

Análisis de consultas

• explain_query - Analiza el plan de ejecución de la consulta

• compare_schemas - Compara esquemas entre dos conexiones

• get_pool_stats - Obtiene estadísticas del pool de conexiones

Túnel SSH / Host de salto

• get_ssh_tunnel_info - Inspecciona el perfil de túnel SSH / host de salto asociado a una conexión (censurado, sin secretos)

Otros

• get_database_stats - Estadísticas de la base de datos

• append_insight - Almacena notas de análisis

• list_insights - Recupera notas almacenadas

Seguridad

• Aplicación 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 mediante OMNISQL_ALLOWED_CONNECTIONS.

• Filtrado de herramientas: deshabilita cualquier herramienta mediante OMNISQL_DISABLED_TOOLS.

• Saneamiento de entradas: los IDs de conexión y los identificadores SQL se sanean para prevenir inyecciones.

• Recomendación: para uso en producción, utiliza también un usuario de solo lectura a nivel de base de datos como defensa en profundidad.

Soporte de formatos de espacio de trabajo

Compatible con ambos formatos de configuración escritos por clientes de BD compatibles con DBeaver:

• Legado: configuración XML en .metadata/.plugins/org.jkiss.dbeaver.core/

• Moderno: configuración JSON en General/.dbeaver/

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

Soporte de túnel SSH / host de salto

Si una conexión tiene un túnel SSH (controlador de red) configurado en tu cliente de BD — incluidos uno o más servidores de salto / hosts de puerta de enlace encadenados — cada consulta nativa, test_connection, transacción y conexión del pool se enruta de forma transparente a través de él. No se requiere configuración de túnel aparte: el servidor abre un reenvío de puerto local a través de la misma cadena de saltos SSH que usaría tu cliente de BD y conecta el controlador nativo (pg, mysql2, mssql) a ese punto final local.

• Admite autenticación por contraseña, clave pública y agente SSH en cada salto.

• Admite servidores de salto encadenados (localhost -> jump host(s) -> final SSH host -> database).

• Los túneles se abren una vez por conexión y se reutilizan entre consultas; se cierran al apagar.

• Usa get_ssh_tunnel_info para inspeccionar el perfil de túnel/host de salto de una conexión (host, puerto, tipo de autenticación, número de servidores de salto) sin exponer ningún secreto.

• Si no se puede recuperar una contraseña o frase de contraseña de clave desde el almacén de credenciales cifrado del espacio de trabajo, establece OMNISQL_SSH_PASSWORD, OMNISQL_SSH_PASSPHRASE o OMNISQL_SSH_PRIVATE_KEY_PATH como respaldo.

Soporte de Trino / Presto

Las conexiones Trino funcionan a través de HTTPS/HTTP (autenticación básica) usando el mismo host/usuario/contraseña ya guardados para la conexión. Algunas notas específicas de Trino:

• El catálogo/esquema son opcionales. Si la conexión no tiene un catálogo/esquema predeterminado configurado (algo común al explorar varios catálogos en DBeaver), las consultas deben calificar completamente las tablas como catalog.schema.table.

• list_tables y get_table_schema no dependen del catálogo por diseño (mediante system.jdbc.tables/system.jdbc.columns), por lo que funcionan sin un catálogo predeterminado, pero en un clúster grande con varios catálogos esto escanea los metadatos de todos los catálogos, lo que puede ser lento y puede devolver filas duplicadas si el mismo nombre de tabla existe en más de un catálogo/esquema. Para una búsqueda rápida y sin ambigüedades, usa execute_query con DESCRIBE catalog.schema.table en su lugar.

• El túnel SSH (arriba) funciona igual para las conexiones Trino que para cualquier otro controlador.

• Trino no tiene un modelo de sesión/transacción persistente en este servidor: begin_transaction y el pool de conexiones no están disponibles para conexiones Trino (igual que SQLite).

Desarrollo

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

Licencia

MIT