@cocaxcode/database-mcp

Resumen rápido

El servidor MCP más completo para bases de datos. 33 herramientas en 3 motores (PostgreSQL, MySQL, SQLite), con grupos de conexiones, gestión de conexiones con nombre, rollback automático, dump/restore, auto-descubrimiento de esquemas mediante Recursos MCP, e historial completo de consultas — todo desde lenguaje natural.

Esto no es solo un ejecutor de consultas. Es un banco de trabajo completo para bases de datos: organiza conexiones en grupos limitados a tus directorios de proyecto, establece valores predeterminados que persisten entre sesiones, inspecciona esquemas en tres niveles de detalle, obtén instantáneas previas a la mutación en cada escritura, deshaz errores con SQL inverso, haz dump y restaura bases de datos completas, y rastrea cada consulta que ejecutas — por proyecto, por conexión.

Cada conexión pertenece a un grupo. Los grupos tienen ámbitos (directorios), una conexión predeterminada y una conexión activa. Cuando trabajas dentro de un directorio con ámbito, solo ves las conexiones de ese grupo — sin desorden, sin confusión.

Tú describes lo que necesitas. La IA lee tu esquema, escribe el SQL y lo ejecuta de forma segura — con inyección automática de LIMIT, instantáneas previas a la mutación y confirmación antes de operaciones destructivas. Sin cuentas en la nube, sin ORMs, sin archivos de configuración. Las credenciales nunca salen de tu máquina. Todo se ejecuta localmente.

Funciona con Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, Gemini CLI y cualquier cliente compatible con MCP.

Related MCP server: Database MCP Server

Solo habla con él

No necesitas memorizar nombres de herramientas ni sintaxis SQL. Solo di lo que quieres.

> "Connect to my local PostgreSQL on port 5432, database myapp, user admin"

> "Create a group called backend and add this directory"

> "Connect to my PostgreSQL on localhost, put it in the backend group"

> "Set local-pg as the default connection"

> "Show me all tables"

> "What columns does the users table have?"

> "Show me the last 10 orders with the customer name"
  -> AI reads FKs from schema, builds the JOIN, applies LIMIT 10

> "Insert a test user called Alice"
  -> Snapshot captured for rollback

> "Oops, undo that"
  -> Rows restored via reverse SQL

> "Switch to the production database for this session"
  -> Instant context change, all queries now go to prod

> "Delete all inactive users"
  -> "This will affect N rows. Call again with confirm=true to proceed."

> "What did I run today?"
  -> Full query history with timestamps and execution times

> "Dump the database — structure and data"
  -> SQL file generated, ready for restore

La IA ya conoce tu esquema mediante Recursos MCP. Lee db://schema para descubrir tablas y db://tables/{name}/schema para columnas, claves foráneas e índices. Cuando pides datos entre tablas, construye los JOINs correctos automáticamente.

Grupos de conexiones

Cada conexión pertenece a un grupo. Los grupos son la unidad organizativa de tus conexiones de base de datos — mantienen todo con ámbito, limpio y automático.

Un grupo tiene tres conceptos clave:

• Ámbitos: directorios que comparten las conexiones del grupo. Cuando trabajas dentro de un directorio con ámbito, solo ves las conexiones de ese grupo. Sin desorden global.

• Predeterminada: la conexión que se activa automáticamente cuando entras en un directorio con ámbito. Persiste entre sesiones.

• Activa: la conexión que se está usando ahora mismo. Solo para la sesión — se restablece a la predeterminada al reiniciar.

Este es un flujo de trabajo práctico:

"Create a group called backend"
"Add this directory as scope"
"Create a PostgreSQL connection called local-dev in the backend group"   <- auto-default (first connection)
"Create another called production in backend"
"List connections"                                                       <- shows local-dev (active, default)
"Switch to production"                                                   <- session only
"Set production as default"                                              <- persists between sessions

La primera conexión añadida a un grupo se convierte en la predeterminada automáticamente. Cambiar de conexión solo modifica la activa para la sesión actual — al reiniciar vuelves a la predeterminada. Si quieres que el cambio sea permanente, establece una nueva predeterminada explícitamente.

Esto significa que puedes cambiar a producción con seguridad para una consulta rápida y saber que la próxima vez que abras el proyecto, volverás a estar en tu base de datos de desarrollo.

Instalación

Claude Code

claude mcp add --scope user database -- npx -y @cocaxcode/database-mcp@latest

Claude Desktop

Añade a tu archivo de configuración (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows):

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Añade a .cursor/mcp.json o .windsurf/mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Añade a .vscode/mcp.json:

{
  "servers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

codex mcp add database -- npx -y @cocaxcode/database-mcp@latest

O añade a ~/.codex/config.toml:

[mcp_servers.database]
command = "npx"
args = ["-y", "@cocaxcode/database-mcp@latest"]

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

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Instalación de drivers

Instala solo el driver que necesites — se cargan dinámicamente en tiempo de ejecución:

npm install -g postgres       # PostgreSQL (postgres.js)
npm install -g mysql2         # MySQL
npm install -g sql.js         # SQLite (runs in-process, no native bindings)

Nota: Cuando uses npx, los drivers deben instalarse globalmente. Si instalas el servidor globalmente (npm install -g @cocaxcode/database-mcp), los drivers pueden ser locales o globales.

Características

Multi-base de datos, una interfaz

La mayoría de los servidores MCP de bases de datos te obligan a reconfigurar las credenciales en cada sesión. Este no. Las conexiones con nombre persisten dentro de los grupos — créalas una vez, úsalas para siempre.

Las conexiones con nombre funcionan como ramas de git. Creas dev, staging, prod una vez dentro de un grupo y siempre están ahí. Cambiar es instantáneo — un comando, cero reconfiguración:

"Create a group called my-project and add this directory as scope"
"Create a connection called dev with host localhost, database myapp, user admin in my-project"
"Create a read-only connection called analytics pointing to ./data/metrics.db in my-project"
"Switch to dev"               -> queries go to PostgreSQL
"Switch to analytics"         -> queries go to SQLite
"Duplicate dev as dev-readonly with read-only mode"

Conexiones con ámbito de grupo significan que diferentes proyectos ven diferentes bases de datos automáticamente. ¿Trabajando en el proyecto A? Ves el grupo y las conexiones del proyecto A. Cambia al directorio del proyecto B y este toma el grupo del proyecto B con su propia predeterminada. Sin cambio manual, sin interferencia entre proyectos:

"Create a group called frontend with scope /home/user/frontend"
"Create a group called backend with scope /home/user/backend"

Ahora cada directorio tiene su propio conjunto aislado de conexiones.

Credenciales 100% locales. Cada conexión se almacena como un archivo JSON en ~/.database-mcp/connections/. Las contraseñas nunca salen de tu máquina. Nada se envía a la nube. Nada se confirma en git. Tus credenciales son tuyas.

Gestión en vivo. Crea, duplica, renombra, prueba, exporta y cambia conexiones a mitad de conversación. Sin necesidad de reiniciar, sin editar archivos de configuración, sin pérdida de contexto.

Seguridad integrada

Instantáneas de rollback

Cada mutación captura una instantánea del estado previo. Deshaz cualquier cosa.

"Show me available rollbacks"
"Rollback the last delete"
  -> "This will INSERT 47 rows back into orders. Confirm?"
  -> Rows restored via reverse SQL

Introspección de esquemas

Tres niveles de detalle, con filtrado por patrón:

"List all tables"                         -> names only (fast)
"Show me the users table with columns"    -> columns + types + nullable
"Full schema for orders including FKs"    -> columns + foreign keys + indexes
"Tables starting with user"              -> pattern: 'user%'

Los Recursos MCP (db://schema y db://tables/{name}/schema) dan a los agentes de IA acceso automático a tu esquema — sin SQL manual para consultas multi-tabla.

Ejecución de consultas con EXPLAIN

"Show me all users"
  -> SELECT * FROM users LIMIT 100         <- auto LIMIT

"Show the execution plan for this query"
  -> EXPLAIN ANALYZE with dialect-specific syntax (PostgreSQL/MySQL/SQLite)

Modos de compresión (v0.3+)

Los resultados SQL a menudo contienen columnas TEXT / JSON / HTML que pueden ocupar kilobytes por fila. Los agentes de IA pagan por cada byte que llega a la ventana de contexto. execute_query, execute_mutation y explain_query aceptan cuatro parámetros opcionales que reducen el 60-95% de esos tokens manteniendo las filas y la estructura intactas.

Modos:

• minimal — solo rowCount, executionTimeMs, affectedRows y una vista previa de la primera fila. Ideal para confirmación de INSERT/UPDATE/DELETE, consultas COUNT, sondeos. Ahorra ~90-95% de tokens.

• normal (predeterminado) — filas completas, pero cada celda truncada a max_cell_bytes con un marcador …(+NB). Preserva la estructura de la tabla. Ahorra ~60-80% de tokens en filas anchas.

• full — resultado completo sin tocar. Úsalo cuando necesites el valor completo de cada celda.

Ahorro típico en SELECT * FROM blog_posts LIMIT 100 donde content es ~2KB de HTML por fila (~200KB en total):

Para una comparación directa contra psql puro con números medidos, consulta Alternativas nativas más abajo.

Recuperando el resultado completo: cada respuesta comprimida incluye un call_id. Si necesitas las celdas completas más tarde, llama a inspect_last_query({ call_id }) — sin re-ejecutar el SQL, preservando la carga de la base de datos y cualquier efecto secundario. Los resultados se mantienen en un búfer circular de 20 ranuras y se persisten en ~/.database-mcp/last-queries/ con un TTL de 1 hora.

// Example: normal (default) response
{
  "call_id": "k3m9a2xp",
  "columns": ["id", "title", "content"],
  "rows": [
    { "id": 1, "title": "Hello", "content": "<h1>Long HTML…(+1847B)" }
  ],
  "rowCount": 1,
  "executionTimeMs": 12,
  "cells_truncated": 1,
  "hint": "1 cell(s) truncated to 500 bytes. Use inspect_last_query({ call_id: \"k3m9a2xp\" }) for full values.",
  "tokens_saved_estimate": 462
}

Alternativas nativas: coste real de tokens

Cómo se compara este MCP con las opciones nativas que tiene Claude Code cuando database no está disponible (Bash + psql, sqlite3, CLI de mysql, etc.).

En resumen: comparado con psql puro, execute_query ahorra entre 78% y 96% de tokens de contexto dependiendo del modo, sin pérdida de información de depuración. Medido en una llamada real a SELECT * FROM blog_posts LIMIT 5 en una tabla de PostgreSQL con una columna content de ~1 KB de HTML por fila:

Por qué los números de esta tabla difieren de la sección «Modos de compresión» anterior: provienen de una consulta real de 5 filas, mientras que la tabla anterior extrapola a un resultado de 100 filas con contenido más pesado. La tendencia y el orden de magnitud son los mismos.

Notas:

• La salida sin procesar de psql empeora a medida que crecen las filas — JSONB y las columnas TEXT largas no tienen filtro nativo. La truncación de celdas de MCP conserva la estructura (número de filas + lista de columnas) mientras colapsa las celdas pesadas con un marcador …(+NB).

• inspect_last_query recupera el resultado completo sin volver a ejecutar el SQL. Con psql tendrías que re-ejecutar, pagando de nuevo CPU de la base de datos y arriesgándote a volver a disparar efectos secundarios en las cláusulas RETURNING.

• El MCP también añade funcionalidades sin equivalente nativo directo: grupos de conexiones acotados a directorios de proyecto, instantáneas de rollback automáticas en mutaciones, historial de consultas, introspección de esquema mediante recursos MCP y volcado/restauración.

• El contexto de esquema se añade al final de la respuesta cuando es relevante (por defecto true para normal/full). Desactívelo con include_schema_context: false si el agente ya conoce el esquema.

• Cada MCP registrado añade una sobrecarga fija de ~300-600 tokens por sesión (su bloque de instrucciones + nombres de herramientas). Punto de equilibrio típico: 1 consulta real por sesión.

Volcado y restauración

Copia de seguridad completa de la base de datos en formato SQL — solo estructura o estructura + datos.

"Dump the database"
  -> Choose: structure only or full
  -> Choose: all tables or specific ones
  -> SQL file saved to .database-mcp/dumps/

"Restore from the last dump"
  -> Lists available dumps, asks for confirmation, executes

El SQL generado gestiona DROP TABLE IF EXISTS, la desactivación/activación de FK y DDL adaptado al dialecto.

Historial de consultas

Cada consulta se registra por proyecto con marca de tiempo, conexión, tiempo de ejecución y tipo de resultado.

"What queries did I run today?"
"Show me only mutations"
"History for the prod connection"

Exportar e importar conexiones

"Export all connections"                    -> JSON with masked passwords
"Export with secrets included"             -> JSON with real credentials
"Import these connections: { ... }"        -> creates missing connections

Referencia de herramientas

33 herramientas en 8 categorías, más 2 recursos MCP:

Recursos: db://schema · db://tables/{tableName}/schema

Consejo: nunca necesitas llamar a estas herramientas directamente. Solo describe lo que quieres y la IA elige la correcta.

Almacenamiento

El almacenamiento se divide en dos ubicaciones por diseño. Esta separación es intencional y resuelve un problema real: tus credenciales te pertenecen, el historial de tu proyecto pertenece al proyecto.

Global: ~/.database-mcp/ — grupos, conexiones, credenciales y ajustes. Reside en tu directorio personal. Nunca dentro de un proyecto. Nunca en git. Nunca se comparte con nadie a menos que las exportes explícitamente.

Por proyecto: {project}/.database-mcp/ — historial de consultas, instantáneas de rollback y volcados de base de datos. Reside dentro del directorio del proyecto y se añade automáticamente a .gitignore en la primera escritura.

~/.database-mcp/                          # Global (configurable via DATABASE_MCP_DIR)
├── groups/                               # Connection groups with scopes and defaults
├── connections/                          # Connection configs (credentials, chmod 600)
├── project-conns.json                    # Session-only active connections (cleared on restart)
└── config.json                           # Server config (limits)

{your-project}/.database-mcp/            # Per-project (auto-gitignored)
├── history.json                          # Query history (max 5000)
├── rollbacks.json                        # Pre-mutation snapshots (max 1000)
└── dumps/
    └── {conn}-{timestamp}-{mode}.sql     # Database dumps

El resultado: puedes compartir un repositorio de proyecto libremente — los colaboradores reciben el historial y la estructura de rollback, pero cero credenciales. Ellos crean sus propias conexiones y grupos localmente.

Configuración

Configurable desde la conversación o mediante variables de entorno:

"Set max rollbacks to 2000"
"Set max history to 10000"

Prioridad: variable de entorno > configuración guardada > valor por defecto.

Advertencia: si sobrescribes DATABASE_MCP_DIR con una ruta dentro de un repositorio git, añade .database-mcp/ a tu .gitignore para evitar subir credenciales.

Arquitectura

src/
├── index.ts              # Entry point (StdioServerTransport)
├── server.ts             # createServer() factory
├── tools/                # 33 tool handlers (one file per category)
├── resources/            # MCP Resources (schema auto-discovery)
├── services/             # Business logic
│   ├── connection-manager    # Lazy connect, driver caching
│   ├── schema-introspector   # Multi-dialect introspection (3 detail levels)
│   ├── query-executor        # Read/mutation/explain with safety
│   ├── rollback-manager      # Snapshot capture + reverse SQL
│   ├── history-logger        # Per-project query log
│   └── dump-manager          # Dump/restore (SQL generation)
├── drivers/              # Database adapters (postgres, mysql, sqlite)
├── lib/                  # Types, storage, sanitization
└── utils/                # SQL classifier, parser, formatter

• Cero dependencias en tiempo de ejecución aparte de @modelcontextprotocol/sdk y zod

• TypeScript estricto — sin any

• Carga dinámica de controladores — import('postgres') / import('mysql2/promise') / import('sql.js') en tiempo de ejecución

• < 60KB empaquetado con tsup

• Patrón de fábrica — createServer(storageDir?, projectDir?) para instancias de prueba aisladas

MIT · Creado por cocaxcode