easy-mysql-mcp

Un servidor ligero del Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA inspeccionar y consultar una base de datos MySQL a través de una interfaz de herramientas segura y estructurada.

Este proyecto utiliza Node.js, TypeScript, el SDK oficial de MCP y mysql2/promise. Se ejecuta sobre stdio, por lo que puede ser utilizado directamente por clientes MCP como Claude Desktop.

Características

• Agrupación de conexiones MySQL (pooling) impulsada por mysql2/promise

• Herramienta de consulta de solo lectura para la recuperación de datos

• Herramienta de ejecución para sentencias de modificación de datos

• Herramientas de descubrimiento de esquemas para tablas, vistas, índices y disparadores (triggers)

• Inspección del plan de consulta con EXPLAIN

• Inspección del usuario actual y sus privilegios

• Protección de stdout para evitar que los registros que no son de MCP contaminen el protocolo stdio

Requisitos

• Node.js 18 o superior

• npm

• Una base de datos compatible con MySQL accesible

Instalación

Ejecuta el servidor directamente con npx:

npx -y easy-mysql-mcp

Para desarrollo local después de clonar el repositorio:

cd easy-mysql-mcp
npm install
npm run build

Configuración

Configura el servidor con variables de entorno. Puedes proporcionarlas a través de la configuración de tu cliente MCP o creando un archivo .env local.

Ejemplo de .env:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

Uso

Configura tu cliente MCP para iniciar el paquete a través de npx.

Para desarrollo local, compila primero el código fuente de TypeScript:

npm run build

Inicia el servidor MCP:

npm start

El servidor se comunica a través de stdio y normalmente es iniciado por un cliente MCP en lugar de ejecutarse manualmente.

Ejemplo de Claude Desktop

Añade el servidor a tu claude_desktop_config.json:

{
  "mcpServers": {
    "easy-mysql-mcp": {
      "command": "npx",
      "args": ["-y", "easy-mysql-mcp"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Reinicia Claude Desktop después de actualizar la configuración.

Herramientas disponibles

Notas de seguridad

• Utiliza un usuario de MySQL dedicado con los permisos mínimos que necesite tu asistente.

• Prefiere credenciales de base de datos de solo lectura si solo necesitas inspección y generación de informes.

• Ten cuidado con mysql_execute, ya que puede modificar datos.

• No subas archivos .env o credenciales reales de base de datos a GitHub.

• Revisa el SQL generado antes de ejecutarlo contra datos de producción.

Desarrollo

npm run dev

Esto ejecuta TypeScript en modo de vigilancia (watch mode).

Para crear una compilación de producción:

npm run build

Estructura del proyecto

src/
  db.ts       MySQL pool and query helpers
  index.ts    MCP server and tool registration
  proxy.ts    stdout protection for stdio-based MCP transport

Licencia

ISC