Servidor MCP para MySQL basado en NodeJS

Un servidor de Protocolo de Contexto de Modelo que proporciona acceso a bases de datos MySQL. Este servidor permite a los LLM inspeccionar esquemas de bases de datos y ejecutar consultas SQL.

Tabla de contenido

• Requisitos

• Instalación

  • Herrería

  • Clonar al repositorio local

• Componentes

• Configuración

• Variables de entorno

• Modo Multi-DB

• Permisos específicos del esquema

• Pruebas

• Solución de problemas

• Contribuyendo

• Licencia

Requisitos

• Node.js v18 o superior

• MySQL 5.7 o superior (se recomienda MySQL 8.0+)

• Usuario MySQL con permisos adecuados para las operaciones que necesita

• Para operaciones de escritura: usuario MySQL con privilegios INSERTAR, ACTUALIZAR y/o ELIMINAR

Instalación

Hay varias formas de instalar y configurar el servidor MCP, pero la más común sería consultar este sitio web https://smithery.ai/server/@benborla29/mcp-server-mysql

Cursor

Para Cursor IDE, puede instalar este servidor MCP con el siguiente comando en su proyecto:

1. Visita https://smithery.ai/server/@benborla29/mcp-server-mysql

2. Siga las instrucciones para el cursor

MCP Get proporciona un registro centralizado de servidores MCP y simplifica el proceso de instalación.

Uso de NPM/PNPM

Para la instalación manual:

Después de la instalación manual, deberá configurar su aplicación LLM para usar el servidor MCP (consulte la sección Configuración a continuación).

Ejecución desde el repositorio local

Si desea clonar y ejecutar este servidor MCP directamente desde el código fuente, siga estos pasos:

1. Clonar el repositorio

   git clone https://github.com/benborla/mcp-server-mysql.git cd mcp-server-mysql

2. Instalar dependencias

   npm install # or pnpm install

3. Construir el proyecto

   npm run build # or pnpm run build

4. Configurar Claude Desktop

   Agregue lo siguiente a su archivo de configuración de Claude Desktop ( claude_desktop_config.json ):

   { "mcpServers": { "mcp_server_mysql": { "command": "/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false", "PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"` } } } }

   Reemplazar:

   • /path/to/node con la ruta completa a su binario Node.js (encuéntrelo con which node )

   • /full/path/to/mcp-server-mysql con la ruta completa a donde clonó el repositorio

   • Configure las credenciales de MySQL para que coincidan con su entorno

5. Probar el servidor

   # Run the server directly to test node dist/index.js

   Si se conecta correctamente a MySQL, estará listo para usarlo con Claude Desktop.

Componentes

Herramientas

• consulta_mysql

  • Ejecutar consultas SQL contra la base de datos conectada

  • Entrada: sql (cadena): La consulta SQL a ejecutar

  • De forma predeterminada, limitado a operaciones de SOLO LECTURA

  • Operaciones de escritura opcionales (cuando se habilitan mediante configuración):

    • INSERTAR: Agregar nuevos datos a las tablas (requiere ALLOW_INSERT_OPERATION=true )

    • ACTUALIZACIÓN: Modificar datos existentes (requiere ALLOW_UPDATE_OPERATION=true )

    • ELIMINAR: Eliminar datos (requiere ALLOW_DELETE_OPERATION=true )

  • Todas las operaciones se ejecutan dentro de una transacción con un manejo adecuado de confirmación y reversión.

  • Admite declaraciones preparadas para el manejo seguro de parámetros

  • Tiempos de espera de consulta y paginación de resultados configurables

  • Estadísticas de ejecución de consultas integradas

Recursos

El servidor proporciona información de base de datos completa:

• Esquemas de tabla

  • Información del esquema JSON para cada tabla

  • Nombres de columnas y tipos de datos

  • Información y restricciones del índice

  • Relaciones de clave externa

  • Estadísticas y métricas de la tabla

  • Descubierto automáticamente a partir de metadatos de la base de datos

Características de seguridad

• Prevención de inyección SQL mediante sentencias preparadas

• Consultar las capacidades de listas blancas/negras

• Limitación de velocidad para la ejecución de consultas

• Análisis de la complejidad de las consultas

• Cifrado de conexión configurable

• Aplicación de transacciones de solo lectura

Optimizaciones de rendimiento

• Agrupación de conexiones optimizada

• Almacenamiento en caché de resultados de consultas

• Transmisión de grandes conjuntos de resultados

• Análisis del plan de ejecución de consultas

• Tiempos de espera de consulta configurables

Monitoreo y depuración

• Registro completo de consultas

• Recopilación de métricas de rendimiento

• Seguimiento y generación de informes de errores

• Puntos finales de comprobación de estado

• Estadísticas de ejecución de consultas

Configuración

Configuración automática con Smithery

Si instaló con Smithery, su configuración ya está configurada. Puede verla o modificarla con:

Al reconfigurar, puede actualizar cualquiera de los detalles de conexión de MySQL, así como la configuración de la operación de escritura:

• Configuración básica de conexión :

  • Host MySQL, puerto, usuario, contraseña, base de datos

  • Configuración SSL/TLS (si su base de datos requiere conexiones seguras)

• Permisos de operación de escritura :

  • Permitir operaciones INSERTAR: Establezca en verdadero si desea permitir agregar nuevos datos

  • Permitir operaciones de ACTUALIZACIÓN: Establezca en verdadero si desea permitir la actualización de datos existentes

  • Permitir operaciones DELETE: Establezca en verdadero si desea permitir la eliminación de datos

Por razones de seguridad, todas las operaciones de escritura están deshabilitadas por defecto. Active esta configuración solo si necesita específicamente que Claude modifique los datos de su base de datos.

Opciones de configuración avanzadas

Para tener más control sobre el comportamiento del servidor MCP, puede utilizar estas opciones de configuración avanzadas:

Variables de entorno

Conexión básica

• MYSQL_SOCKET_PATH : Ruta de socket Unix para conexiones locales (por ejemplo, "/tmp/mysql.sock")

• MYSQL_HOST : host del servidor MySQL (predeterminado: "127.0.0.1") - se ignora si se configura MYSQL_SOCKET_PATH

• MYSQL_PORT : puerto del servidor MySQL (predeterminado: "3306") - se ignora si se configura MYSQL_SOCKET_PATH

• MYSQL_USER : nombre de usuario de MySQL (predeterminado: "root")

• MYSQL_PASS : contraseña de MySQL

• MYSQL_DB : Nombre de la base de datos de destino (déjelo vacío para el modo multi-DB)

Configuración de rendimiento

• MYSQL_POOL_SIZE : Tamaño del grupo de conexiones (predeterminado: "10")

• MYSQL_QUERY_TIMEOUT : Tiempo de espera de la consulta en milisegundos (valor predeterminado: "30000")

• MYSQL_CACHE_TTL : Tiempo de vida de la caché en milisegundos (valor predeterminado: "60000")

Configuración de seguridad

• MYSQL_RATE_LIMIT : Máximo de consultas por minuto (predeterminado: "100")

• MYSQL_MAX_QUERY_COMPLEXITY : Puntuación máxima de complejidad de la consulta (valor predeterminado: "1000")

• MYSQL_SSL : Habilitar el cifrado SSL/TLS (valor predeterminado: "falso")

• ALLOW_INSERT_OPERATION : Habilitar operaciones INSERT (predeterminado: "falso")

• ALLOW_UPDATE_OPERATION : Habilitar operaciones de ACTUALIZACIÓN (predeterminado: "falso")

• ALLOW_DELETE_OPERATION : Habilitar operaciones DELETE (predeterminado: "false")

• ALLOW_DDL_OPERATION : Habilitar operaciones DDL (predeterminado: "falso")

• SCHEMA_INSERT_PERMISSIONS : Permisos de INSERCIÓN específicos del esquema

• SCHEMA_UPDATE_PERMISSIONS : Permisos de actualización específicos del esquema

• SCHEMA_DELETE_PERMISSIONS : Permisos DELETE específicos del esquema

• SCHEMA_DDL_PERMISSIONS : Permisos DDL específicos del esquema

• MULTI_DB_WRITE_MODE : Habilita operaciones de escritura en modo multi-DB (predeterminado: "falso")

Configuración de monitorización

• MYSQL_ENABLE_LOGGING : Habilitar el registro de consultas (valor predeterminado: "falso")

• MYSQL_LOG_LEVEL : Nivel de registro (predeterminado: "info")

• MYSQL_METRICS_ENABLED : Habilitar métricas de rendimiento (valor predeterminado: "falso")

Modo Multi-DB

MCP-Server-MySQL admite la conexión a múltiples bases de datos cuando no se ha definido ninguna. Esto permite que LLM consulte cualquier base de datos a la que el usuario MySQL tenga acceso. Para más información, consulte README-MULTI-DB.md .

Habilitación del modo Multi-DB

Para habilitar el modo multi-DB, simplemente deje vacía la variable de entorno MYSQL_DB . En el modo multi-DB, las consultas requieren la cualificación del esquema:

Permisos específicos del esquema

Para un control preciso de las operaciones de la base de datos, MCP-Server-MySQL ahora admite permisos específicos del esquema. Esto permite que distintas bases de datos tengan distintos niveles de acceso (solo lectura, lectura y escritura, etc.).

Ejemplo de configuración

Para obtener detalles completos y recomendaciones de seguridad, consulte README-MULTI-DB.md .

Pruebas

Configuración de la base de datos

Antes de ejecutar pruebas, debe configurar la base de datos de prueba y cargarla con datos de prueba:

1. Crear una base de datos de prueba y un usuario

   -- Connect as root and create test database CREATE DATABASE IF NOT EXISTS mcp_test; -- Create test user with appropriate permissions CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password'; GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost'; FLUSH PRIVILEGES;

2. Ejecutar el script de configuración de la base de datos

   # Run the database setup script pnpm run setup:test:db

   Esto creará las tablas y los datos de inicialización necesarios. El script se encuentra en scripts/setup-test-db.ts

3. Configurar el entorno de prueba Cree un archivo .env.test en la raíz del proyecto (si no existe):

   MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=mcp_test MYSQL_PASS=mcp_test_password MYSQL_DB=mcp_test

4. Actualizar scripts de package.json Agregue estos scripts a su package.json:

   { "scripts": { "setup:test:db": "ts-node scripts/setup-test-db.ts", "pretest": "pnpm run setup:test:db", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage" } }

Ejecución de pruebas

El proyecto incluye un conjunto de pruebas integral para garantizar la funcionalidad y la confiabilidad:

Ejecución de evaluaciones

El paquete evals carga un cliente mcp que ejecuta el archivo index.ts, por lo que no es necesario reconstruir entre pruebas. Puede cargar variables de entorno prefijando el comando npx. Puede encontrar la documentación completa aquí .

Solución de problemas

Problemas comunes

1. Problemas de conexión

   • Verifique que el servidor MySQL esté en ejecución y sea accesible

   • Comprobar credenciales y permisos

   • Asegúrese de que la configuración de SSL/TLS sea correcta si está habilitada

   • Intente conectarse con un cliente MySQL para confirmar el acceso

2. Problemas de rendimiento

   • Ajustar el tamaño del grupo de conexiones

   • Configurar valores de tiempo de espera de consulta

   • Habilitar el almacenamiento en caché de consultas si es necesario

   • Comprobar la configuración de la complejidad de la consulta

   • Supervisar el uso de los recursos del servidor

3. Restricciones de seguridad

   • Revisar la configuración de limitación de velocidad

   • Comprobar la configuración de la lista blanca/lista negra de consultas

   • Verificar la configuración de SSL/TLS

   • Asegúrese de que el usuario tenga los permisos MySQL adecuados

4. Resolución de ruta Si encuentra un error "No se pudo conectar al servidor MCP mcp-server-mysql", establezca explícitamente la ruta de todos los binarios requeridos:

¿Dónde puedo encontrar la ruta del contenedor de mi ? Ejecute el siguiente comando para obtenerlo:

Para PATH

Para NODE_PATH

5. Problemas específicos de Claude Desktop

   • Si ve registros de "Servidor desconectado" en Claude Desktop, verifique los registros en ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log

   • Asegúrese de utilizar la ruta absoluta tanto al binario del nodo como al script del servidor

   • Verifique si su archivo .env se está cargando correctamente; use variables de entorno explícitas en la configuración

   • Intente ejecutar el servidor directamente desde la línea de comandos para ver si hay problemas de conexión

   • Si necesita operaciones de escritura (INSERTAR, ACTUALIZAR, ELIMINAR), configure los indicadores apropiados como "verdadero" en su configuración:

     "env": { "ALLOW_INSERT_OPERATION": "true", // Enable INSERT operations "ALLOW_UPDATE_OPERATION": "true", // Enable UPDATE operations "ALLOW_DELETE_OPERATION": "true" // Enable DELETE operations }

   • Asegúrese de que su usuario MySQL tenga los permisos adecuados para las operaciones que está habilitando

   • Para la configuración de ejecución directa, utilice:

     { "mcpServers": { "mcp_server_mysql": { "command": "/full/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database" } } } }

6. Problemas de autenticación

   • Para MySQL 8.0+, asegúrese de que el servidor admita el complemento de autenticación caching_sha2_password

   • Compruebe si su usuario MySQL está configurado con el método de autenticación correcto

   • Intente crear un usuario con autenticación heredada si es necesario:

     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

     @lizhuangs

7. Me encuentro con Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from el error. Pruebe esta solución alternativa:

Gracias a @lizhuangs

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios a https://github.com/benborla/mcp-server-mysql

Muchas gracias a los siguientes colaboradores:

Configuración de desarrollo

1. Clonar el repositorio

2. Instalar dependencias: pnpm install

3. Construya el proyecto: pnpm run build

4. Ejecutar pruebas: pnpm test

Hoja de ruta del proyecto

Estamos trabajando activamente para mejorar este servidor MCP. Consulta nuestro CHANGELOG.md para obtener más información sobre las funciones planificadas, incluyendo:

• Capacidades de consulta mejoradas con declaraciones preparadas

• Funciones de seguridad avanzadas

• Optimizaciones de rendimiento

• Monitoreo integral

• Información de esquema ampliada

Si desea contribuir a alguna de estas áreas, consulte los problemas en GitHub o abra uno nuevo para discutir sus ideas.

Envío de cambios

1. Bifurcar el repositorio

2. Crea una rama de funciones: git checkout -b feature/your-feature-name

3. Confirme sus cambios: git commit -am 'Add some feature'

4. Empujar a la rama: git push origin feature/your-feature-name

5. Enviar una solicitud de extracción

Licencia

Este servidor MCP está licenciado bajo la licencia MIT. Consulte el archivo de licencia para obtener más información.