Servidor MCP de consultas MySQL

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona consultas de solo lectura a bases de datos MySQL para asistentes de IA. Ejecute consultas, explore estructuras de bases de datos e investigue sus datos directamente desde sus herramientas basadas en IA.

Herramientas de IA compatibles

Este servidor MCP funciona con cualquier herramienta que admita el Protocolo de contexto de modelo, incluidas:

Cursor IDE : configurado en .cursor/mcp.json
Anthropic Claude : Úselo con un cliente MCP compatible
Otros asistentes de IA compatibles con MCP : siga las instrucciones de configuración de MCP de la herramienta

Características y limitaciones

Qué hace

✅ Ejecutar consultas MySQL de solo lectura (solo SELECT, SHOW, DESCRIBE)
✅ Trabajar con entornos predefinidos (local, desarrollo, staging, producción)
✅ Proporcionar información de bases de datos y metadatos
✅ Lista de entornos de bases de datos disponibles
✅ Admite conexiones SSL para acceso seguro a la base de datos
✅ Implementar tiempos de espera de consultas para evitar operaciones de larga duración

Lo que no hace

❌ Ejecutar operaciones de escritura (INSERTAR, ACTUALIZAR, ELIMINAR, CREAR, ALTERAR, etc.)
❌ Admite nombres de entornos personalizados (limitados a local, desarrollo, ensayo y producción)
❌ Proporcionar capacidades de diseño de bases de datos o generación de esquemas
❌ Funciona como una herramienta completa de gestión de bases de datos

Esta herramienta está diseñada específicamente para la investigación y exploración de datos mediante consultas de solo lectura. No está diseñada para la administración de bases de datos, la gestión de esquemas ni la modificación de datos.

Instalación rápida

# Install globally with npm
npm install -g mysql-query-mcp-server

# Or run directly with npx
npx mysql-query-mcp-server

Instrucciones de configuración

Configure su herramienta de IA para usar el servidor MCP

Cree o edite su archivo de configuración MCP (por ejemplo, .cursor/mcp.json para Cursor IDE):

Configuración básica:

{
  "mysql": {
    "name": "MySQL Query MCP",
    "description": "MySQL read-only query access through MCP",
    "type": "bin", 
    "enabled": true,
    "bin": "mysql-query-mcp"
  }
}

Configuración completa con credenciales de base de datos:

{
  "mysql": {
    "command": "npx",
    "args": ["mysql-query-mcp-server@latest"],
    "env": {
      "LOCAL_DB_HOST": "localhost",
      "LOCAL_DB_USER": "root",
      "LOCAL_DB_PASS": "<YOUR_LOCAL_DB_PASSWORD>",
      "LOCAL_DB_NAME": "your_database",
      "LOCAL_DB_PORT": "3306",
      
      "DEVELOPMENT_DB_HOST": "dev.example.com",
      "DEVELOPMENT_DB_USER": "<DEV_USER>",
      "DEVELOPMENT_DB_PASS": "<DEV_PASSWORD>",
      "DEVELOPMENT_DB_NAME": "your_database",
      "DEVELOPMENT_DB_PORT": "3306",
      
      "STAGING_DB_HOST": "staging.example.com",
      "STAGING_DB_USER": "<STAGING_USER>",
      "STAGING_DB_PASS": "<STAGING_PASSWORD>",
      "STAGING_DB_NAME": "your_database",
      "STAGING_DB_PORT": "3306",
      
      "PRODUCTION_DB_HOST": "prod.example.com",
      "PRODUCTION_DB_USER": "<PRODUCTION_USER>",
      "PRODUCTION_DB_PASS": "<PRODUCTION_PASSWORD>",
      "PRODUCTION_DB_NAME": "your_database",
      "PRODUCTION_DB_PORT": "3306",
      
      "DEBUG": "false",
      "MCP_MYSQL_SSL": "true",
      "MCP_MYSQL_REJECT_UNAUTHORIZED": "false"
    }
  }
}

Cómo elegir el enfoque de configuración adecuado

Hay dos formas de configurar el servidor MySQL MCP:

Configuración binaria ( type: "bin" , bin: "mysql-query-mcp" )
- Cuándo usarlo : cuando haya instalado el paquete globalmente ( npm install -g mysql-query-mcp-server )
- Ventajas : Configuración más sencilla
- Contras : Requiere instalación global
Configuración de comando ( command: "npx" , args: ["mysql-query-mcp-server@latest"] )
- Cuándo usarlo : Cuando desee utilizar la última versión sin instalarla globalmente
- Ventajas : No requiere instalación global, toda la configuración en un solo archivo
- Contras : Configuración más compleja

Elija el enfoque que mejor se adapte a su flujo de trabajo. Ambos métodos funcionarán correctamente con cualquier asistente de IA compatible con MCP.

Notas importantes de configuración

Debe utilizar los nombres de entorno completos: LOCAL_, DEVELOPMENT_, STAGING_, PRODUCTION_
Las abreviaturas como DEV_ o PROD_ no funcionarán
Las configuraciones globales como DEBUG, MCP_MYSQL_SSL se aplican a todos los entornos
Se debe configurar al menos un entorno (normalmente "local")
Solo necesitas configurar los entornos que planeas utilizar
Por razones de seguridad, considere usar variables de entorno o almacenamiento de credenciales seguro para las credenciales de producción.

Opciones de configuración

Variable de entorno	Descripción	Por defecto
DEPURAR	Habilitar el registro de depuración	FALSO
[ENV]_HOST_DB	Host de base de datos para el entorno	-
[ENV]_USUARIO_DB	Nombre de usuario de la base de datos	-
[ENV]_DB_PASS	Contraseña de la base de datos	-
[ENV]_NOMBRE_DE_BASE_DE_DATOS	Nombre de la base de datos	-
[ENV]_PUERTO_DB	Puerto de base de datos	3306
[ENV]_DB_SSL	Habilitar la conexión SSL	FALSO
MCP_MYSQL_SSL	Habilitar SSL para todas las conexiones	FALSO
MCP_MYSQL_RECHAZAR_NO AUTORIZADO	Verificar certificados SSL	verdadero

Integración con asistentes de IA

Tu asistente de IA puede interactuar con bases de datos MySQL a través del servidor MCP. Aquí tienes algunos ejemplos:

Consultas de ejemplo:

Can you use the query tool to show me the first 10 users from the database? Use the local environment.

I need to analyze our sales data. Can you run a SQL query to get the total sales per region for last month from the development database?

Can you use the info tool to check what tables are available in the staging database?

Can you list all the available database environments we have configured?

Uso de las herramientas MySQL MCP

El servidor MySQL Query MCP proporciona tres herramientas principales que su asistente de IA puede utilizar:

1. consulta

Ejecutar consultas SQL de solo lectura en un entorno específico:

Use the query tool to run:
SELECT * FROM customers WHERE signup_date > '2023-01-01' LIMIT 10;
on the development environment

2. información

Obtenga información detallada sobre su base de datos:

Use the info tool to check the status of our production database.

3. entornos

Enumere todos los entornos configurados desde su configuración:

Use the environments tool to show me which database environments are available.

Herramientas disponibles

El servidor MySQL Query MCP proporciona tres herramientas principales:

1. consulta

Ejecutar consultas SQL de solo lectura:

-- Example query to run with the query tool
SELECT * FROM users LIMIT 10;

Tipos de consulta admitidos (estrictamente limitados a) :

Sentencias SELECT
Comandos SHOW
Tablas DESCRIBE/DESC

2. información

Obtenga información detallada sobre su base de datos:

Versión del servidor
Estado de la conexión
Variables de base de datos
Lista de procesos
Bases de datos disponibles

3. entornos

Enumere todos los entornos configurados desde su configuración:

Use the environments tool to show me which database environments are available.

Consideraciones de seguridad

✅ Solo se permiten consultas de solo lectura (SELECT, SHOW, DESCRIBE)
✅ Cada entorno tiene su propio grupo de conexiones aisladas
✅ Se admiten conexiones SSL para entornos de producción
✅ Los tiempos de espera de las consultas evitan operaciones fuera de control
⚠️ Considere utilizar una gestión segura de credenciales para las credenciales de la base de datos

Solución de problemas

Problemas de conexión

Si tiene problemas para conectarse:

Verifique las credenciales de su base de datos en su configuración de MCP
Asegúrese de que el servidor MySQL esté en ejecución y sea accesible
Comprobar las reglas del firewall que bloquean las conexiones
Habilite el modo de depuración configurando DEBUG=true en su configuración

Errores comunes

Error: No hay ningún grupo de conexiones disponible para el entorno

Asegúrese de haber definido todas las variables de entorno necesarias para ese entorno
Comprueba que estás utilizando uno de los nombres de entorno admitidos (local, desarrollo, ensayo, producción)

Error: Falló la ejecución de la consulta

Verifique su sintaxis SQL
Comprueba que solo estás utilizando tipos de consulta compatibles (SELECT, SHOW, DESCRIBE)
Asegúrese de que su consulta sea realmente de solo lectura

Para una solución de problemas más completa, consulte la Guía de solución de problemas .

Para obtener ejemplos de cómo integrarse con asistentes de IA, consulte Ejemplos de integración .

Para obtener detalles de implementación sobre el protocolo MCP, consulte el archivo README de MCP .

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Proceso de CI/CD y lanzamiento

Este proyecto utiliza GitHub Actions para integración continua y lanzamientos automatizados.

Flujo de trabajo de CI/CD

El pipeline de CI/CD consta de:

Compilar y probar : se ejecuta en cada envío a las ramas main y develop , y en las solicitudes de extracción a estas ramas
- Prueba el código base con Node.js 16.x y 18.x
- Asegura que el paquete se compile correctamente
- Valida que todas las pruebas pasen
Lanzamiento : se ejecuta cuando se envían cambios a la rama main y el trabajo de compilación/prueba tiene éxito.
- Utiliza release-please para administrar las actualizaciones de versiones y del registro de cambios
- Crea una PR de lanzamiento con cambios de versión basados en confirmaciones convencionales
- Se publica automáticamente en npm cuando se fusiona un PR de lanzamiento

Proceso de liberación

El proyecto sigue el control de versiones semántico :

Versión principal : cambios importantes (no compatible con versiones anteriores)
Versión menor : Nuevas funciones (compatible con versiones anteriores)
Versión del parche : correcciones de errores y mejoras menores

Los commits deben seguir el formato de commits convencionales :

feat: add new feature - Mejora de versión menor
fix: resolve bug - Actualización de la versión del parche
docs: update documentation - Sin aumento de versión
chore: update dependencies - Sin aumento de versión
BREAKING CHANGE: change API - Aumento importante de la versión

Cuando envías a main , release-please analizará las confirmaciones y creará o actualizará automáticamente un PR de lanzamiento con las actualizaciones de versión y las entradas del registro de cambios apropiadas.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Autor

Abou Koné - Líder de ingeniería y director de tecnología

Para obtener más información o ayuda, abra un problema en el repositorio de GitHub.

MySQL Query MCP Server

Integrations