MariaDB-MCP
MariaDB-MCP is an MCP server for MariaDB/MySQL that lets clients inspect databases and run controlled SQL over stdio or HTTP/SSE.
Connect using stdio by default or HTTP/SSE with
--http <port>, optionally protected by API key authentication.List all accessible databases.
List tables in a specified database.
Get a table's column schema, including types, nullable, keys, defaults, and extras.
Get a table's schema including foreign-key relations.
Execute SQL queries (
SELECT,SHOW,DESCRIBE) with optional parameters; read-only mode blocks writes and file functions likeLOAD_FILE/INTO OUTFILE.Create a database when write mode is enabled (
MCP_READ_ONLY=false).Enforce query timeout and max row limits, with explicit truncation warnings; metadata tools fail rather than return incomplete listings.
Use database selection aliases (
database_name,database,db,schema) and verify the active database before each query.Support SSL, connection pooling, configurable charset, logging, Docker/Compose, and read-only database user grants.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MariaDB-MCP list tables in database genoma"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).Límites de ejecución: tiempo máximo por consulta (
MCP_QUERY_TIMEOUT) y tope de filas devueltas (MCP_MAX_ROWS), con aviso explícito cuando un resultado se recorta.Autenticación por API key en el transporte HTTP (
MCP_API_KEY), con comparación en tiempo constante.Logging a
stderr(compatible con stdio transport) y archivos rotados diariamente conwinston.Docker y Docker Compose listos para usar.
Related MCP server: mysql-mcp-server
Herramientas MCP expuestas
Herramienta | Descripción |
| Lista todas las bases de datos accesibles. |
| Lista las tablas de una base de datos. |
| Obtiene columnas, tipos, nullable, keys, defaults y extras. |
| Igual que |
| Ejecuta queries |
| Crea una base de datos (requiere |
Selección de base de datos
Todas las herramientas que trabajan sobre una base de datos aceptan el parámetro
database_name y sus alias database, db y schema (útil para clientes que
renombran el parámetro). La conexión se cambia explícitamente con changeUser() y
se verifica con SELECT DATABASE() antes de ejecutar la query, de modo que la
consulta siempre corre sobre la base de datos indicada en la herramienta y nunca
sobre la de una llamada anterior.
execute_sql: si no se envíadatabase_name, se usaDB_NAME(la configurada). El servidor avisa en el log cuando se ejecuta sin base de datos explícita.El resto de herramientas exigen
database_namey devuelven un error claro con los alias aceptados si falta.
Límites de ejecución
Tiempo máximo por consulta (
MCP_QUERY_TIMEOUT, 30 s por defecto): se aplica conSET SESSION max_statement_time(MariaDB). Si el servidor no lo admite se intentamax_execution_time(MySQL, en milisegundos y solo paraSELECT); si no hay ninguno disponible, el límite se desactiva y se avisa una sola vez en el log, en lugar de romper todas las consultas.Cuando una consulta agota el tiempo, el servidor la cancela y devuelve un error claro (
MCP_QUERY_TIMEOUT=...). La conexión sigue siendo válida y vuelve al pool, así que unSELECTdesbocado no bloquea el servidor ni contamina las llamadas siguientes.Tope de filas (
MCP_MAX_ROWS, 1000 por defecto): lo aplica el propio servidor consql_select_limit = MCP_MAX_ROWS + 1, de modo que un resultado gigante no viaja por la red. Al recortar,execute_sqlresponde así en lugar de devolver un array:
{
"rows": [ { "n": 0 }, { "n": 1 } ],
"truncated": true,
"row_limit": 1000,
"received_rows": 1001,
"message": "Resultado truncado a las primeras 1000 filas (límite MCP_MAX_ROWS)..."
} Si el resultado cabe en el tope, la respuesta sigue siendo el array de filas de
siempre (no hay cambio de forma). Con MCP_MAX_ROWS=0 el tope se desactiva.
Las herramientas de metadatos (
list_databases,list_tables,get_table_schema,get_table_schema_with_relations) fallan con un error claro si el tope recorta su resultado, en lugar de devolver un listado incompleto: es peor concluir que una tabla no existe que recibir el aviso de subirMCP_MAX_ROWS.Los límites se reaplican tras cada cambio de base de datos, porque
COM_CHANGE_USERdevuelve las variables de sesión a su valor por defecto.
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 installConfiguración
Copia el archivo de ejemplo y ajusta tus credenciales:
cp .env.example .envVariables disponibles:
Variable | Descripción | Default |
| Host del servidor MariaDB |
|
| Puerto |
|
| Usuario |
|
| Contraseña | (vacío) |
| Base de datos por defecto |
|
| Charset de conexión |
|
| Habilitar SSL |
|
| Ruta al certificado CA | (vacío) |
| Ruta al certificado cliente | (vacío) |
| Ruta a la clave privada cliente | (vacío) |
| Verificar certificado |
|
| Verificar identidad del host |
|
| Modo solo lectura |
|
| Tamaño máximo del pool |
|
| Segundos máximos por consulta ( |
|
| Filas máximas devueltas por herramienta ( |
|
| API key(s) exigida(s) en el transporte HTTP, separadas por coma | (vacío = sin auth) |
|
| exigir si hay clave |
| Nivel de log ( |
|
| Orígenes CORS separados por coma | (vacío) |
| Hosts permitidos separados por coma |
|
Uso
Modo stdio (por defecto)
npm start
# o
node src/index.jsModo HTTP/SSE
node src/index.js --http 3000Ayuda
node src/index.js --helpAutenticación API key (transporte HTTP)
Define una o varias claves en .env para proteger el endpoint MCP:
MCP_API_KEY=mi-clave-secreta
# o varias: MCP_API_KEY=clave-1,clave-2Con la clave definida, todas las rutas salvo /health devuelven 401 si no
se envía. El cliente debe incluir una de estas cabeceras:
Authorization: Bearer mi-clave-secreta
X-API-Key: mi-clave-secreta# Verificar
$ curl -i -X POST http://localhost:3005/mcp -H 'Authorization: Bearer mi-clave-secreta'
HTTP/1.1 401 Unauthorized # sin clave
HTTP/1.1 200 OK # con clave correcta
$ curl -i http://localhost:3005/health # sigue sin clave para el healthcheck
# → {"status":"healthy"} (sin credenciales: solo el estado)/health nunca exige credenciales, para no romper el healthcheck de Docker y de los
orquestadores. Cuando hay autenticación configurada solo responde { status }; el
detalle (server, version, database, readOnly, pool) requiere la misma clave que
/mcp, igual que el mensaje de error cuando la base de datos no responde.
Variables relacionadas:
Variable | Descripción |
| Claves válidas separadas por coma. Vacío → autenticación deshabilitada (se avisa en el log). |
|
|
La comparación de claves se hace en tiempo constante (hash SHA-256 +
timingSafeEqual). La comparación no se registra en los logs.
Docker
Construir y ejecutar
# Modo stdio ( foreground )
docker-compose run --rm mcp-server
# Modo HTTP ( background )
docker-compose up -d mcp-serverAsegú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.Límites de ejecución por sesión (tiempo máximo de consulta y tope de filas), que además acotan el consumo de memoria del servidor y el tamaño de las respuestas.
Autenticación API key opcional en el transporte HTTP (
MCP_API_KEY), con comparación en tiempo constante;/healthqueda abierto para el healthcheck, pero solo devuelve{ status }cuando hay autenticación configurada.Solo lectura real con grants:
MCP_READ_ONLYfiltra por prefijo de sentencia y es una comodidad, no una frontera de seguridad (un CTE conUPDATE, una función almacenada o una sentencia preparada se le escapan). La garantía la da el usuario de base de datos, y al arrancar se avisa si ese usuario tiene privilegios de escritura. Ejemplo listo para ejecutar enexamples/mariadb-readonly-user.sql:CREATE USER IF NOT EXISTS 'mcp_ro'@'%' IDENTIFIED BY '...'; GRANT SELECT, SHOW VIEW ON `genoma`.* TO 'mcp_ro'@'%';y en
.env:DB_USER=mcp_rocon suDB_PASSWORD.Cada ejecución verifica con
SELECT DATABASE()que corre sobre la base de datos solicitada; si no coincide, la conexión se descarta y se devuelve un error en vez de resultados de otra base de datos.
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
├── test/ # Pruebas (node --test)
├── examples/ # Ejemplos, p. ej. usuario MariaDB de solo lectura
├── logs/ # Archivos de log rotados
├── .env.example
├── .gitignore
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.mdLicencia
MIT
Available Tools
6 toolscreate_databaseA
Crea una nueva base de datos si no existe. Requiere modo escritura (READ_ONLY=false).
Inputs: database_name (required).
execute_sqlA
Ejecuta una consulta SQL (SELECT, SHOW, DESCRIBE) y retorna los resultados. En modo solo lectura (por defecto), se bloquean queries de escritura.
Inputs: sql_query (required), database_name (required), parameters.
get_table_schemaA
Obtiene la estructura de columnas de una tabla (nombre, tipo, nullable, clave, default, extra).
Inputs: table_name (required), database_name (required).
get_table_schema_with_relationsB
Obtiene la estructura de columnas incluyendo relaciones de clave foránea.
Inputs: table_name (required), database_name (required).
list_databasesA
Lista todas las bases de datos accesibles en el servidor MariaDB.
Inputs: no named parameters.
list_tablesB
Lista todas las tablas de una base de datos específica.
Inputs: database_name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clear, non-overlapping purpose: database creation, SQL execution, schema retrieval (with optional relations), and listing databases/tables. The two schema tools are differentiated by the inclusion of foreign key relations.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_database, list_databases, get_table_schema). The style is uniform and predictable.
Six tools cover essential database operations—listing, schema inspection, SQL execution, and database creation—without being excessive or sparse for the server's scope.
The set covers read operations well but lacks explicit tools for dropping databases or altering tables. The execute_sql tool can perform write operations if mode allows, but dedicated tools for update/delete are missing, leaving notable gaps.
Maintenance
Related MCP Connectors
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
Read authorized Loam tables and supported external databases through a bounded MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables read-only interaction with SQL databases through MCP, providing database metadata exploration, sample data retrieval, and secure query execution. Supports MySQL with multiple transport options and built-in security features including SQL injection protection and data sanitization.27 npm5MIT
- AlicenseNot gradedqualityDmaintenanceEnables MySQL database operations through MCP, including executing SQL queries, listing databases and tables, and describing table structures.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables safe querying and optional writing to MySQL databases via MCP tools, with support for schema inspection, connection management, and read-only mode.16 npm3MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to MySQL databases, enabling schema exploration, table inspection, and safe SELECT query execution via MCP.1ISC