MariaDB / MySQL

MariaDB / MySQL MCP Server

Este servidor MCP expone bases de datos MariaDB y MySQL a clientes MCP como Claude Desktop, VS Code y otras herramientas compatibles.

Proporciona herramientas para:

• listar bases de datos disponibles
• listar tablas en una base de datos
• describir esquemas de tablas
• ejecutar consultas SQL

Características

• Comportamiento seguro por defecto: el acceso de solo lectura está habilitado por defecto
• Validación de consultas para bloquear sentencias no permitidas y reducir el riesgo de inyección
• Permisos de escritura configurables mediante variables de entorno
• Protección de tiempo de espera y límite de filas
• Seguridad numérica para IDs de inserción y valores BIGINT devueltos por el controlador MariaDB

Instalación

Opción 1: Instalar desde npm

npm install -g mariadb-mcp-server

Opción 2: Instalar localmente

npm install mariadb-mcp-server

Opción 3: Compilar desde el código fuente

git clone https://github.com/rjsalgado/mariadb-mcp-server.git
cd mariadb-mcp-server
npm install
npm run build

Configuración

Establezca las siguientes variables de entorno antes de iniciar el servidor:

• MARIADB_HOST: Host de la base de datos
• MARIADB_PORT: Puerto de la base de datos (predeterminado: 3306)
• MARIADB_USER: Nombre de usuario de la base de datos
• MARIADB_PASSWORD: Contraseña de la base de datos
• MARIADB_DATABASE: Nombre de la base de datos predeterminada (opcional)
• MARIADB_ALLOW_INSERT: Habilitar sentencias INSERT (true/false)
• MARIADB_ALLOW_UPDATE: Habilitar sentencias UPDATE (true/false)
• MARIADB_ALLOW_DELETE: Habilitar sentencias DELETE (true/false)
• MARIADB_TIMEOUT_MS: Tiempo de espera de consulta en milisegundos (predeterminado: 10000)
• MARIADB_ROW_LIMIT: Número máximo de filas devueltas (predeterminado: 1000)

Ejemplo:

export MARIADB_HOST=localhost
export MARIADB_PORT=3306
export MARIADB_USER=myuser
export MARIADB_PASSWORD=mypassword
export MARIADB_DATABASE=mydb
export MARIADB_ALLOW_INSERT=false
export MARIADB_ALLOW_UPDATE=false
export MARIADB_ALLOW_DELETE=false
export MARIADB_TIMEOUT_MS=10000
export MARIADB_ROW_LIMIT=1000

Configuración de MCP

Usando el paquete npm

{
  "mcpServers": {
    "mariadb": {
      "command": "npx",
      "args": ["mariadb-mcp-server"],
      "env": {
        "MARIADB_HOST": "your-host",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your-user",
        "MARIADB_PASSWORD": "your-password",
        "MARIADB_DATABASE": "your-database",
        "MARIADB_ALLOW_INSERT": "false",
        "MARIADB_ALLOW_UPDATE": "false",
        "MARIADB_ALLOW_DELETE": "false",
        "MARIADB_TIMEOUT_MS": "10000",
        "MARIADB_ROW_LIMIT": "1000"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Usando un servidor local compilado

{
  "mcpServers": {
    "mariadb": {
      "command": "node",
      "args": ["/absolute/path/to/mariadb-mcp-server/dist/index.js"],
      "env": {
        "MARIADB_HOST": "your-host",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your-user",
        "MARIADB_PASSWORD": "your-password",
        "MARIADB_DATABASE": "your-database",
        "MARIADB_ALLOW_INSERT": "false",
        "MARIADB_ALLOW_UPDATE": "false",
        "MARIADB_ALLOW_DELETE": "false",
        "MARIADB_TIMEOUT_MS": "10000",
        "MARIADB_ROW_LIMIT": "1000"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Herramientas disponibles

El servidor registra las siguientes herramientas MCP:

list_databases

Lista todas las bases de datos accesibles para el usuario configurado.

list_tables

Lista las tablas de una base de datos específica.

Parámetros:

• database (opcional): nombre de la base de datos a inspeccionar

describe_table

Devuelve el esquema de una tabla específica.

Parámetros:

• database (opcional): nombre de la base de datos
• table (obligatorio): nombre de la tabla

execute_query

Ejecuta una consulta SQL.

Parámetros:

• database (opcional): nombre de la base de datos
• query (obligatorio): sentencia SQL a ejecutar

Pruebas

El repositorio incluye scripts para validar el servidor contra una instancia de MariaDB o MySQL.

npm run test:setup
npm run test:tools

O ejecute todo junto:

npm test

Notas

• El servidor es seguro por defecto y solo permite operaciones de solo lectura a menos que los indicadores de escritura estén habilitados explícitamente.
• Las operaciones de escritura siguen sujetas a validación de consultas y límites de tiempo de ejecución.

Solución de problemas

Si encuentra problemas:

1. Revise los registros del servidor para ver mensajes de error
2. Verifique sus credenciales y detalles de conexión de MariaDB/MySQL
3. Asegúrese de que su usuario de MariaDB/MySQL tenga los permisos adecuados
4. Compruebe que su consulta sea de solo lectura y esté correctamente formateada

Inspiración https://github.com/dpflucas/mysql-mcp-server

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.