db-mcp

Un servidor MCP de solo lectura que le da a un agente de IA un acceso seguro a una pequeña base de datos SQLite de tienda (shop.db): descubrimiento del esquema, consultas SQL de solo lectura en formato libre e informes analíticos predefinidos.

Instalación

npm install

Related MCP server: SQLite Read-Only MCP Server

Configuración

El servidor lee SHOP_DB_PATH del entorno del proceso para localizar el archivo de la base de datos. Es opcional: si no está definida, el servidor usa shop.db en la raíz del proyecto. Los archivos .env no se leen automáticamente (no hay dependencia de dotenv ni ninguna opción --env-file en los scripts de package.json); .env.example se incluye únicamente como recordatorio del nombre de la variable. Define SHOP_DB_PATH en el entorno real en el que se ejecute el servidor — para un cliente MCP stdio, eso significa la clave env de su configuración (consulta «Conectar un cliente» más abajo).

Compilación

npm run build

Ejecución

npm start
# or directly:
node dist/index.js

El servidor se comunica por MCP a través de stdio — está pensado para que lo lance un cliente MCP o un host como proceso hijo, no para ejecutarse de forma interactiva.

Conectar un cliente

Configuración genérica de un cliente MCP stdio:

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

Claude Desktop: añade el mismo bloque bajo mcpServers en claude_desktop_config.json (consulta MCP.md para saber la ubicación del archivo de configuración según el sistema operativo) y, a continuación, reinicia Claude Desktop.

Tools

Notas de seguridad

• La conexión a la base de datos se abre con { readonly: true, fileMustExist: true }: el propio motor de SQLite rechaza físicamente cualquier escritura, sin importar el SQL que se envíe.

• La herramienta query además valida que la entrada sea una sola sentencia SELECT (o WITH ... SELECT) antes de que llegue siquiera a la base de datos, rechazando INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/PRAGMA/ATTACH/DETACH/REPLACE/VACUUM/REINDEX/TRIGGER y la entrada con varias sentencias, con un mensaje de error claro.

• Los errores se capturan en el borde de cada herramienta y se devuelven como un resultado de herramienta MCP con isError: true y un mensaje breve: nunca se envían al cliente ni rastreos de pila ni rutas del sistema de archivos.

• Todos los registros van a stderr (console.error): stdout está reservado en exclusiva para el flujo del protocolo JSON-RPC.

Pruebas

npm test

Ejecuta node --test (vía tsx) sobre todos los archivos *.test.ts: pruebas unitarias para el guard de SQL, la conexión a la base de datos y la lógica de consulta de cada herramienta contra la shop.db real, además de una prueba de extremo a extremo que lanza el servidor compilado y lo maneja con un cliente MCP real a través de stdio.

Docker

docker build -t db-mcp .
docker run -i db-mcp

No es necesario para ejecutar el servidor localmente (la configuración del cliente anterior espera un proceso node local), pero se ofrece como una alternativa para verificarlo o ejecutarlo.