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
  • Escritorio de Claude
  • Cursor
  • Herrería
  • Obtener MCP
  • 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:

Escritorio de Claude

Para configurar manualmente el servidor MCP para Claude Desktop App, agregue lo siguiente a su archivo claude_desktop_config.json (normalmente ubicado en su directorio de usuario):

Cursor

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

No olvides reemplazar los valores env en ese comando. Si tienes la última versión de Cursor (v0.47 y posteriores), simplemente copia y pega la configuración a continuación:

mcp.json

Uso de herrería

La forma más sencilla de instalar y configurar este servidor MCP es a través de Smithery :

Durante la configuración, se le solicitará que ingrese los datos de su conexión MySQL. Smithery realizará automáticamente lo siguiente:

• Configurar las variables de entorno correctas
• Configure su aplicación LLM para utilizar el servidor MCP
• Pruebe la conexión a su base de datos MySQL
• Proporcionar solución de problemas útil si es necesario
• Configurar los ajustes de la operación de escritura (permisos INSERTAR, ACTUALIZAR, ELIMINAR)

La instalación solicitará los siguientes detalles de conexión:

• Host MySQL (predeterminado: 127.0.0.1)
• Puerto MySQL (predeterminado: 3306)
• Nombre de usuario de MySQL
• Contraseña de MySQL
• Nombre de la base de datos MySQL
• Configuración SSL (si es necesario)
• Permisos de operaciones de escritura:
  • Permitir operaciones INSERT (predeterminado: falso)
  • Permitir operaciones de ACTUALIZACIÓN (predeterminado: falso)
  • Permitir operaciones DELETE (predeterminado: falso)

Por razones de seguridad, las operaciones de escritura están deshabilitadas por defecto. Habilítelas solo si necesita que Claude modifique los datos de su base de datos.

Uso de MCP Get

También puedes instalar este paquete usando MCP Get :

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 DesktopAgregue 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_HOST : host del servidor MySQL (predeterminado: "127.0.0.1")
• MYSQL_PORT : Puerto del servidor MySQL (predeterminado: "3306")
• 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 (valor predeterminado: "falso")

Configuración de monitorización

• MYSQL_ENABLE_LOGGING : Habilitar el registro de consultas (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 la variable de entorno MYSQL_DB vacía. 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:

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 node ? 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

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.