MariaDB MCP Server (JavaScript)
Servidor MCP escrito en Node.js / JavaScript para interactuar con bases de datos MariaDB/MySQL.
Características
- Transporte stdio compatible con el protocolo MCP (Model Context Protocol).
- Transporte HTTP/SSE preparado para extenderse con un bridge web.
- Conexión pool usando
mysql2/promisecon tamaño configurable. - Soporte SSL con CA, certificados cliente y configuración de verificación.
- Modo solo lectura (READ_ONLY) que bloquea queries de escritura y funciones de archivo (
LOAD_FILE,INTO OUTFILE). - Logging a
stderr(compatible con stdio transport) y archivos rotados diariamente conwinston. - Docker y Docker Compose listos para usar.
Herramientas MCP expuestas
| Herramienta | Descripción |
|---|---|
list_databases |
Lista todas las bases de datos accesibles. |
list_tables |
Lista las tablas de una base de datos. |
get_table_schema |
Obtiene columnas, tipos, nullable, keys, defaults y extras. |
get_table_schema_with_relations |
Igual que get_table_schema pero incluye claves foráneas. |
execute_sql |
Ejecuta queries SELECT/SHOW/DESCRIBE. Valida parámetros y modo solo lectura. |
create_database |
Crea una base de datos (requiere MCP_READ_ONLY=false). |
Requisitos
- Node.js >= 18 (recomendado 20 LTS)
- MariaDB/MySQL accesible desde la red del servidor
Instalación
# Clonar o copiar la carpeta MariaDB-MCP
cd MariaDB-MCP
# Instalar dependencias
npm install
Configuración
Copia el archivo de ejemplo y ajusta tus credenciales:
cp .env.example .env
Variables disponibles:
| Variable | Descripción | Default |
|---|---|---|
DB_HOST |
Host del servidor MariaDB | localhost |
DB_PORT |
Puerto | 3306 |
DB_USER |
Usuario | root |
DB_PASSWORD |
Contraseña | (vacío) |
DB_NAME |
Base de datos por defecto | genoma |
DB_CHARSET |
Charset de conexión | utf8mb4 |
DB_SSL |
Habilitar SSL | false |
DB_SSL_CA |
Ruta al certificado CA | (vacío) |
DB_SSL_CERT |
Ruta al certificado cliente | (vacío) |
DB_SSL_KEY |
Ruta a la clave privada cliente | (vacío) |
DB_SSL_VERIFY_CERT |
Verificar certificado | true |
DB_SSL_VERIFY_IDENTITY |
Verificar identidad del host | true |
MCP_READ_ONLY |
Modo solo lectura | true |
MCP_MAX_POOL_SIZE |
Tamaño máximo del pool | 10 |
LOG_LEVEL |
Nivel de log (debug,info,warn,error) |
info |
ALLOWED_ORIGINS |
Orígenes CORS separados por coma | (vacío) |
ALLOWED_HOSTS |
Hosts permitidos separados por coma | localhost,127.0.0.1 |
Uso
Modo stdio (por defecto)
npm start
# o
node src/index.js
Modo HTTP/SSE
node src/index.js --http 3000
Ayuda
node src/index.js --help
Docker
Construir y ejecutar
# Modo stdio ( foreground )
docker-compose run --rm mcp-server
# Modo HTTP ( background )
docker-compose up -d mcp-server
Asegúrese de que las variables de entorno estén definidas en un archivo
.envo en el shell antes de ejecutardocker-compose.
Seguridad
- MULTI_STATEMENTS y LOCAL_INFILE están desactivados en el pool de conexiones.
- En modo
READ_ONLY, solo se permiten queries que inicien conSELECT,SHOW,DESC,DESCRIBEoUSE. - Se bloquean explícitamente las funciones
LOAD_FILE()y sentenciasINTO OUTFILE/DUMPFILE. - Se detecta y se alerta si el usuario de base de datos posee el privilegio global
FILE.
Estructura del proyecto
MariaDB-MCP/
├── src/
│ ├── index.js # Punto de entrada y CLI
│ ├── server.js # Lógica MCP, pool y herramientas
│ ├── config.js # Variables de entorno
│ └── logger.js # Configuración de winston
├── logs/ # Archivos de log rotados
├── .env.example
├── .gitignore
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md
Licencia
MIT
