Skip to main content
Glama
dsh-databases

dsh-databases

by nvznc

dsh-databases — MCP de bases de datos para DSH

Servidor Model Context Protocol para DeepSeek Harness que expone SQL Server, MySQL/MariaDB y PostgreSQL al agente. Permite elegir con qué conexión trabajar (por nombre) y qué motor usar, explorar bases, tablas y columnas, y ejecutar consultas devolviendo JSON acotado.

  • Transporte: stdio (lo lanza DSH como subproceso).

  • Drivers: mssql, mysql2 y pg — JavaScript puro, sin ODBC ni DLLs.

  • Múltiples conexiones con nombre, con motor propio cada una.

  • Modo: lectura + escritura opcional (MSSQL_ALLOW_WRITE); run_query siempre es de solo lectura.

Tres formas de elegir base de datos y motor

Forma

Para qué sirve

Dónde

.env

Conexión única rápida ("default")

variables MSSQL_*

configs/connections.json

Lista fija de conexiones por nombre y motor

archivo JSON versionable (sin secretos)

save_connection (herramienta MCP)

El agente guarda conexiones nuevas en caliente

~/.dsh-mcp-sql/connections.json

Además, cualquier herramienta acepta connection (nombre) y engine (mssql | mysql | postgres) en la misma llamada.

Related MCP server: MariaDB MCP Server

Herramientas MCP

Con serverName: db DSH las expone como mcp__db__<nombre>:

Herramienta

Qué hace

list_connections

Motores disponibles y conexiones configuradas (sin contraseñas).

save_connection

Crea o reemplaza una conexión con nombre (motor, host, puerto, base, usuario, contraseña, opciones).

remove_connection

Elimina una conexión guardada con save_connection.

test_connection

Conecta y devuelve versión/host/usuario reales, o el error exacto.

list_databases

Bases accesibles con estado y tamaño.

list_tables

Tablas y/o vistas con filas aproximadas.

describe_table

Columnas, tipos, índices y claves foráneas.

run_query

Una sentencia de lectura (SELECT/WITH; en mysql/postgres también EXPLAIN, SHOW, DESCRIBE).

server_info

Versión, host, usuario y arranque del servidor.

execute_sql

Escritura/DDL, solo con MSSQL_ALLOW_WRITE=true.

Instalación

npm install
npm run build
Copy-Item .env.example .env        # credenciales
Copy-Item configs/connections.example.json configs/connections.json

Configuración (.env)

Variable

Por defecto

Descripción

MSSQL_ENGINE

mssql

Motor de la conexión por defecto: mssql | mysql | postgres.

MSSQL_SERVER / MSSQL_PORT

localhost / 1433

Host y puerto.

MSSQL_DATABASE

master

Base por defecto.

MSSQL_USER / MSSQL_PASSWORD

—

Credenciales de la conexión por defecto.

MSSQL_ENCRYPT / MSSQL_TRUST_SERVER_CERTIFICATE

true / true

TLS para SQL Server.

MSSQL_ALLOW_WRITE

false

Habilita execute_sql.

MSSQL_ALLOWED_DATABASES

vacío

Lista blanca de bases separada por comas.

MSSQL_MAX_ROWS

200

Filas por consulta (tope 5000).

MSSQL_QUERY_TIMEOUT_MS / MSSQL_CONNECT_TIMEOUT_MS

30000 / 15000

Timeouts.

MSSQL_CONFIGS

configs/connections.json

Archivo de conexiones declaradas.

DSH_MCP_SQL_CONNECTION

—

Conexión usada cuando la herramienta no indica ninguna.

DSH_MCP_SQL_HOME

~/.dsh-mcp-sql

Dónde se guardan las conexiones creadas con save_connection.

MSSQL_LOG_LEVEL

info

debug | info | warn | error (logs por stderr).

Conexiones declaradas (configs/connections.json)

{
  "connections": [
    {
      "name": "farmaluz",
      "engine": "mssql",
      "host": "localhost",
      "port": 1433,
      "database": "FarmaluzAdminDb",
      "user": "mcp_sql",
      "password": "tu-clave",
      "options": { "encrypt": true, "trustServerCertificate": true }
    },
    {
      "name": "core-mysql",
      "engine": "mysql",
      "host": "10.0.0.5",
      "port": 3306,
      "database": "erp",
      "user": "consulta",
      "password": "tu-clave",
      "options": { "ssl": false }
    }
  ]
}

configs/connections.json está en .gitignore (contiene contraseñas); versiona connections.example.json como plantilla. Alternativa sin secretos en el repo: dejar password vacío aquí y guardarlo con save_connection, que escribe en ~/.dsh-mcp-sql/connections.json.

Ejemplos de uso desde el agente

list_connections
test_connection            {"connection": "farmaluz"}
list_tables                {"connection": "core-mysql", "kind": "tables"}
describe_table             {"connection": "core-mysql", "table": "facturas"}
run_query                  {"connection": "farmaluz", "sql": "SELECT TOP 10 * FROM SAPROD"}
save_connection            {"name": "pg-test", "engine": "postgres", "host": "localhost",
                            "database": "postgres", "user": "postgres", "password": "..."}

Registro en DSH

Como plugin instalado (recomendado)

El paquete declara dsh.bundle.patch (cordis.patch.yml), así que DSH lo gestiona como bundle: aparece en Plugins del sidebar y se puede instalar desde el índice del market.

Como fila del perfil (sin empaquetar)

En %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml, sustituyendo <RUTA> por la carpeta donde clonaste este repo:

- insert:
    - id: mcp-databases
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: db
        transport: stdio
        command: 'node'
        args:
          - '<RUTA>/dist/index.js'
        cwd: '<RUTA>'
        toolCallTimeoutMs: 120000

Importante: la entrada va dentro de un insert:. El loader de DSH solo aplica parches por id existente; una entrada nueva suelta se descarta con patch: entry "mcp-databases" not found.

Instalar desde el market

Plugins → Discover → Add index source con la URL del índice publicado (https://nvznc.github.io/dsh-databases/index.json), busca Databases e instala. DSH clona el repositorio en el commit listado y monta el bundle; tras instalar, define las credenciales (.env o save_connection) y reinicia para que el servidor MCP arranque.

Índice del plugin market (GitHub)

El índice sigue el formato 1 de DSH (@deepseek-ai/dsh-plugin-market-index): JSON válido, versiones fijadas a un commit de Git en https://, y engines.dsh.

npm run index -- --repo https://github.com/nvznc/dsh-databases --commit <sha40> --version 1.0.0
npm run index:check          # valida el índice contra las reglas del formato
git add site && git commit -m "market: index" && git push

Cada vez que publiques una versión nueva: cambia version en package.json, compila, súbelo, y regenera el índice con el nuevo commit (git rev-parse HEAD).

Publicación en GitHub Pages (Settings → Pages → Deploy from a branch → main / /site). Una vez publicada, en DSH: Plugins → Discover → Add index source con https://nvznc.github.io/dsh-databases/index.json.

Seguridad

  • run_query pasa por una guarda de solo lectura (src/guard.ts): enmascara comentarios, literales y identificadores citados, exige una sola sentencia, empieza por SELECT/WITH (EXPLAIN/SHOW solo en mysql/postgres) y rechaza palabras clave de escritura, COPY, pg_sleep, xp_cmdshell…

  • Los permisos reales los decide el motor: usa logins de solo lectura (sql/create-mcp-login.sql crea uno para SQL Server).

  • Las contraseñas nunca se imprimen en los logs ni en list_connections; configs/connections.json está ignorado por git.

  • execute_sql solo existe con MSSQL_ALLOW_WRITE=true.

Scripts

npm run build        # compila TypeScript a dist/
npm start            # arranca el servidor (normalmente lo lanza DSH)
npm run verify       # comprobaciones reales contra cada conexión (incluye rollback de escritura)
npm run smoke -- farmaluz "SELECT 1 AS ok"
npm run index        # genera site/index.json para el plugin market
npm run index:check  # valida el índice

Solución de problemas

Síntoma

Causa / solución

Login failed for user …

Credenciales desincronizadas; revisa .env o configs/connections.json y prueba test_connection.

No se pudo abrir la conexión TCP

Puerto/TCP del motor: MSSQL_PORT o port de la conexión (1433/3306/5432).

Faltan credenciales para la conexión …

Completa user/password en .env o guarda la conexión con save_connection.

Las tools no aparecen en DSH

Usa insert: en cordis.patch.yml y que dist/index.js exista (npm run build).

Las conexiones nuevas no aparecen

Editar connections.json requiere reiniciar el servidor MCP; save_connection aplica al instante.

Estructura

src/
  config.ts        # .env, rutas de datos y validación de variables
  guard.ts         # guarda de solo lectura (cualquier motor)
  tools.ts         # definición de herramientas MCP
  index.ts         # arranque stdio y apagado ordenado
  engines/
    types.ts       # contratos EngineAdapter / ConnectionProfile
    registry.ts    # resolución de conexiones y guardado
    mssql.ts       # SQL Server (pool por base)
    mysql.ts       # MySQL / MariaDB
    postgres.ts    # PostgreSQL
scripts/           # smoke, verify, generador y validador del índice
sql/               # creación/borrado del login de solo lectura en SQL Server
site/              # índice publicable del plugin market (GitHub Pages)

Available Tools

9 tools
describe_tableDescribir una tablaA
Read-onlyIdempotent

Devuelve el esquema detallado de una tabla o vista: columnas con tipo, nulabilidad, valor por defecto, auto-incremento/identidad, índices y claves foráneas. Úsala antes de escribir consultas.

Inputs: table (required), engine, schema, database, +1 more.

list_connectionsListar conexiones y motoresA
Read-onlyIdempotent

Muestra los motores soportados (mssql, mysql, postgres) y las conexiones configuradas: la del .env ("default"), las declaradas en configs/connections.json y las guardadas con save_connection. Usa los nombres que devuelve en el parámetro "connection" del resto de herramientas.

Inputs: no named parameters.

list_databasesListar bases de datosA
Read-onlyIdempotent

Lista las bases de datos a las que tiene acceso la conexión elegida (mssql, mysql o postgres), con estado y tamaño cuando el motor lo expone. Úsala para descubrir qué bases existen antes de consultar tablas.

Inputs: engine, database, connection, includeSystem.

list_tablesListar tablas y vistasA
Read-onlyIdempotent

Lista tablas y/o vistas de la base elegida, filtradas por esquema o por texto en el nombre. Devuelve esquema, nombre, tipo, filas aproximadas y fechas cuando el motor las expone. Es el primer paso para explorar un esquema desconocido en cualquier motor.

Inputs: kind, engine, schema, database, +2 more.

remove_connectionEliminar conexión guardadaA
DestructiveIdempotent

Elimina una conexión creada con save_connection. No afecta a las del .env ni a configs/connections.json.

Inputs: name (required).

run_queryEjecutar consulta de solo lecturaA
Read-onlyIdempotent

Ejecuta una única sentencia de lectura (SELECT/WITH; en mysql/postgres también EXPLAIN, SHOW o DESCRIBE) y devuelve las filas como JSON. No permite escribir ni varias sentencias. Las filas se limitan a 200 por defecto (máximo 5000). Usa list_tables y describe_table para explorar.

Inputs: sql (required), engine, maxRows, database, +1 more.

save_connectionGuardar conexiónA
Idempotent

Guarda (o reemplaza) una conexión con nombre en el archivo de datos del usuario, para luego elegirla con "connection" en list_databases, list_tables, describe_table, run_query y execute_sql. No valida la conexión; usa test_connection después de guardar.

Inputs: name (required), user (required), engine (required), password (required), +4 more.

server_infoInformación del servidorA
Read-onlyIdempotent

Muestra versión, host, usuario actual y fecha de arranque del servidor de la conexión elegida. Sirve para confirmar a qué servidor y motor se está conectando el MCP.

Inputs: engine, database, connection.

test_connectionProbar conexiónA
Read-onlyIdempotent

Abre una conexión y devuelve la información real del servidor (versión, host, usuario) o el error exacto. Úsala después de editar configs/connections.json o de guardar una conexión.

Inputs: engine, database, connection.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes split across connection management, discovery, and querying. The main overlap is between test_connection and server_info, which both return version/host/user for the selected connection, making it easy to pick the wrong one for diagnostics.

    Naming Consistency4/5

    Nearly all names follow a predictable snake_case verb_noun pattern (list_connections, save_connection, list_tables, describe_table, run_query). The only deviation is the noun-only server_info, which is a minor break in the convention.

    Tool Count5/5

    Nine tools is well within the sweet spot and each one covers a distinct facet of database exploration and connection management. Nothing feels bloated or missing at the count level.

    Completeness2/5

    The surface is read-only: run_query explicitly forbids writes and there is no execute_sql tool, yet save_connection's description tells agents to use execute_sql, a dead reference that will cause failures. For a multi-engine database server, missing any DML/DDL path is a significant lifecycle gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs and agents to interact with relational databases (SQL Server, MySQL, PostgreSQL) through MCP tools. Supports executing queries, inserting records, listing tables, and exposing database schemas with secure credential management.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to securely interact with MariaDB and MySQL databases using granular per-connection read/write permissions and transaction support. It allows users to manage multiple database connections, explore schemas, and execute controlled SQL queries through a standardized interface.
      6
      17 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query and modify MySQL and MariaDB databases over MCP, with each connection independently permitting selects, inserts, updates, deletes, and DDL while defaulting to read-only and rejecting anything outside the allowed operations. Connections are configured in JSON, result sets are capped and truncated, and passwords stay server-side.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to query and explore PostgreSQL and MySQL clusters from a single main configuration, with dynamic per-database routing, automatic database discovery and sync, table/schema inspection, and hierarchical write-rule protection that can block or allow specific SQL mutation operations.
      9
      MIT