MySQL MCP Server

Un servidor de base de datos MySQL para asistentes de IA, que permite operaciones CRUD completas, gestión de transacciones y reversión inteligente.

GitHub

Prueba este MCPPatrocinado

Documentación

MySQL MCP Server 🚀

v4.0.0 - ¡Reescritura completa de la arquitectura, más simple y más potente!

Un servidor MCP (Model Context Protocol) de base de datos MySQL potente y fácil de usar, que permite a los asistentes de IA operar bases de datos MySQL de forma segura.

🌟 Características principales

🌐 Protocolo StreamableHTTP - Implementado según la especificación MCP más reciente
🔐 Preconfiguración de headers - Las credenciales no se exponen a la IA, seguro y confiable
🤖 Gestión dinámica por IA - La IA puede ayudarte a añadir/cambiar conexiones de base de datos
🔗 Soporte multi-base de datos - Gestiona múltiples bases de datos simultáneamente y cambia entre ellas en cualquier momento
📊 CRUD completo - Soporta todas las operaciones SQL
🏗️ Arquitectura modular - Estructura de directorios clara, fácil de ampliar

📦 Instalación

Requisitos del entorno

Node.js 18+
MySQL 5.7+ o 8.0+
Cliente MCP (Claude Desktop, Cursor, etc.)

Pasos de instalación

# 克隆项目
git clone https://github.com/guangxiangdebizi/MySQL_MCP.git
cd MySQL_MCP

# 安装依赖
npm install

# 编译
npm run build

# 启动服务器
npm start

⚙️ Métodos de configuración

Método 1: Preconfiguración de headers (recomendado)

Edita el archivo de configuración de MCP:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuración de una sola base de datos

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "timeout": 600,
      "headers": {
        "X-MySQL-Host": "localhost",
        "X-MySQL-Port": "3306",
        "X-MySQL-User": "root",
        "X-MySQL-Password": "your_password",
        "X-MySQL-Database": "your_database"
      }
    }
  }
}

Configuración de múltiples bases de datos

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "timeout": 600,
      "headers": {
        "X-MySQL-Host-1": "prod.mysql.com",
        "X-MySQL-User-1": "prod_user",
        "X-MySQL-Password-1": "prod_pass",
        "X-MySQL-Database-1": "production",
        
        "X-MySQL-Host-2": "test.mysql.com",
        "X-MySQL-User-2": "test_user",
        "X-MySQL-Password-2": "test_pass",
        "X-MySQL-Database-2": "testing"
      }
    }
  }
}

Ventajas:

✅ Las credenciales de la base de datos no se exponen a la IA
✅ Conexión al iniciar, sin necesidad de operación manual
✅ Soporta conexión simultánea a múltiples bases de datos

Método 2: Adición dinámica por IA (flexible)

Sin configurar headers, deja que la IA añada conexiones durante la conversación:

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "timeout": 600
    }
  }
}

Ejemplo de uso:

你: 帮我连接到本地 MySQL，用户名 root，密码 123456，数据库 mydb
AI: [调用 add_connection 工具]

🔧 Lista de herramientas

Gestión de conexiones

Nombre de la herramienta	Descripción	Caso de uso
`add_connection`	Añadir conexión de base de datos	La IA añade nuevas conexiones dinámicamente
`list_connections`	Listar todas las conexiones	Ver qué bases de datos hay actualmente
`select_database`	Seleccionar base de datos activa	Cambiar a otra base de datos
`remove_connection`	Eliminar conexión	Limpiar conexiones innecesarias

Operaciones de consulta

Nombre de la herramienta	Descripción	Caso de uso
`execute_query`	Ejecutar SQL	Cualquier operación SQL (SELECT, INSERT, UPDATE, DELETE)
`show_tables`	Mostrar todas las tablas	Conocer rápidamente la estructura de la base de datos
`describe_table`	Ver estructura de tabla	Ver campos, tipos, datos de muestra
`show_databases`	Mostrar todas las bases de datos	Ver la lista de bases de datos accesibles

🎮 Ejemplos de uso

Escenario 1: Uso con preconfiguración de headers

你: 显示所有表
AI: [调用 show_tables] 
    📊 数据库表列表 (共 5 个表)
    1. users
    2. orders
    3. products
    ...

你: 查看 users 表的结构
AI: [调用 describe_table，参数：users]
    📋 表结构: users
    字段信息:
    - id (INT, 主键)
    - name (VARCHAR)
    - email (VARCHAR)
    ...

Escenario 2: Adición dinámica de conexiones por IA

你: 帮我连接两个数据库：
    1. 生产库：prod.mysql.com，用户 admin，密码 xxx，数据库 shop
    2. 测试库：test.mysql.com，用户 tester，密码 yyy，数据库 shop_test

AI: [调用 add_connection，参数：id=prod, host=prod.mysql.com...]
    [调用 add_connection，参数：id=test, host=test.mysql.com...]
    ✅ 两个数据库连接已添加

你: 列出所有连接
AI: [调用 list_connections]
    📊 当前数据库连接列表 (共 2 个)
    🟢 [1] prod
       └─ prod.mysql.com:3306/shop
       └─ ✅ 当前活跃连接
    ⚪ [2] test
       └─ test.mysql.com:3306/shop_test

你: 切换到测试库
AI: [调用 select_database，参数：test]
    ✅ 已选择数据库: test

你: 查询用户表前 10 条
AI: [调用 execute_query，SQL: SELECT * FROM users LIMIT 10]
    ✅ 查询成功，返回 10 行数据
    [显示 JSON 格式数据]

🏗️ Arquitectura del proyecto

MySQL_MCP/
├── src/
│   ├── index.ts              # 主入口（HTTP Server + 会话管理）
│   ├── database.ts           # 数据库连接管理器
│   └── tools/                # 工具模块
│       ├── index.ts          # 工具统一导出和路由
│       ├── connection.ts     # 连接管理工具
│       └── query.ts          # 查询工具
├── dist/                     # 编译后的 JS 文件
├── package.json
├── tsconfig.json
└── README.md

Diseño principal:

index.ts - Servidor HTTP Express + inicialización del servidor MCP
database.ts - Encapsula el pool de conexiones de la base de datos y la lógica de consulta
tools/ - Cada archivo se encarga de la definición y el manejo de un tipo de herramienta

🔒 Recomendaciones de seguridad

Configuración de permisos de base de datos

Crea un usuario de base de datos dedicado para MCP, limitando los permisos:

-- 创建专用用户
CREATE USER 'mcp_user'@'%' IDENTIFIED BY 'strong_password';

-- 授予必要权限
GRANT SELECT, INSERT, UPDATE, DELETE ON your_database.* TO 'mcp_user'@'%';

-- 生产环境只读用户
GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%';

Seguridad en modo HTTP

✅ Usa preconfiguración de headers para evitar exponer credenciales a la IA
✅ Usa HTTPS en producción (proxy inverso Nginx)
✅ Limita las IPs de acceso (reglas de firewall)
✅ Actualiza periódicamente las contraseñas de la base de datos
✅ Supervisa los registros para detectar accesos anómalos

🚀 Scripts NPM

# 开发模式（TypeScript 直接运行）
npm run dev

# 编译
npm run build

# 生产模式（运行编译后的 JS）
npm start

# 全局安装
npm run install-global

📝 Variables de entorno

Crea el archivo .env (opcional):

# HTTP 服务器端口
PORT=3001

# Node 环境
NODE_ENV=production

❗ Preguntas frecuentes

1. Puerto en uso

Error: EADDRINUSE: address already in use :::3001

Solución: Modifica PORT en el archivo .env, o termina el proceso que ocupa el puerto

# Windows
netstat -ano | findstr :3001
taskkill /F /PID <PID>

# Linux/Mac
lsof -ti:3001 | xargs kill -9

2. Error de conexión

Error: 数据库连接失败

Verifica:

Si el servicio MySQL está en ejecución
Si el host, puerto, usuario y contraseña son correctos
Si el firewall permite la conexión

3. Pérdida de sesión

Problema: Tras reiniciar el servidor aparece "Session not found"

Causa: Las sesiones se almacenan en memoria y se borran al reiniciar

Solución: Actualiza el cliente MCP (reinicialización)

4. Error de conexión cerrada

Error: Can't add new command when connection is in closed state

Causa:

La conexión de la base de datos estuvo inactiva durante mucho tiempo y el servidor MySQL la cerró
La interrupción de la red provocó la desconexión

Solución:

✅ v4.0.5+ ya usa un pool de conexiones en lugar de una conexión única, con soporte automático de:
- Mecanismo de mantenimiento de conexión (Keep-Alive)
- Reconexión automática
- Soporte de consultas concurrentes
Si sigues teniendo problemas, reinicia el servidor MCP

📦 Historial de versiones

v4.0.5 (2025-12-09) - Optimización del pool de conexiones

🎯 Usa un pool de conexiones en lugar de una conexión única
🔄 Mantenimiento automático de conexión (Keep-Alive)
🔌 Mecanismo de reconexión automática
🚀 Soporta consultas concurrentes
🐛 Corrige el error "connection in closed state"

v4.0.0 (2025-12-09) - Nueva arquitectura

🔥 Reescritura completa, nueva arquitectura modular
✨ Basado en el protocolo MCP StreamableHTTP más reciente
🎯 Herramientas simplificadas: gestión de conexiones + operaciones de consulta
🏗️ Estructura de directorios clara: modularización tools/
🚀 Mayor velocidad de respuesta
📖 Comentarios de código más claros

v3.x - Versiones anteriores

Soporta funciones complejas como gestión de transacciones y rollback
Arquitectura más compleja

📞 Soporte y comentarios

🐛 Reportar problemas: GitHub Issues
💡 Sugerencias de funciones: GitHub Discussions
📧 Contactar al autor: guangxiangdebizi@gmail.com

🔧 Solución de problemas

Problema: error `ERR_MODULE_NOT_FOUND`

Mensaje de error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '...@modelcontextprotocol/sdk...'

Solución:

Elimina y reinstala las dependencias:

# 删除旧依赖
rm -rf node_modules package-lock.json  # Linux/Mac
# 或
rmdir /s /q node_modules && del package-lock.json  # Windows

# 清理缓存
npm cache clean --force

# 重新安装
npm install

Verifica la versión de Node.js:

node --version  # 需要 >= 18.0.0

Usa instalación global:

npm install -g @xingyuchen/mysql-mcp-server@latest

Problema: flujo SSE interrumpido

Mensaje de error:

SSE stream disconnected: TypeError: terminated

Solución:

Configura un tiempo de espera más largo o desactívalo en mcp.json:

{
  "mysql-mcp-http": {
    "type": "streamableHttp",
    "url": "http://localhost:3002/mcp",
    "timeout": 0,  // 0 表示无超时限制
    "headers": { ... }
  }
}

Problema: advertencia de vulnerabilidad de seguridad

Mensaje de advertencia:

npm audit: vulnerabilities found

Solución:

# 自动修复
npm audit fix

# 如果还有问题，强制修复
npm audit fix --force

# 重新构建
npm run build

Problema: puerto en uso

Mensaje de error:

Error: listen EADDRINUSE: address already in use :::3002

Solución:

Cambia el puerto (en el archivo .env):

PORT=3003

O cierra el proceso que ocupa el puerto:

# Windows
netstat -ano | findstr :3002
taskkill /PID <进程ID> /F

# Linux/Mac
lsof -i :3002
kill -9 <进程ID>

Obtener más ayuda

📄 Licencia

Apache 2.0 License - Consulta el archivo LICENSE para más detalles

⭐ Si este proyecto te ha sido útil, ¡apóyanos con una estrella!

MySQL MCP Server

Documentación

MySQL MCP Server 🚀

🌟 Características principales

📦 Instalación

Requisitos del entorno

Pasos de instalación

⚙️ Métodos de configuración

Método 1: Preconfiguración de headers (recomendado)

Configuración de una sola base de datos

Configuración de múltiples bases de datos

Método 2: Adición dinámica por IA (flexible)

🔧 Lista de herramientas

Gestión de conexiones

Operaciones de consulta

🎮 Ejemplos de uso

Escenario 1: Uso con preconfiguración de headers

Escenario 2: Adición dinámica de conexiones por IA

🏗️ Arquitectura del proyecto

🔒 Recomendaciones de seguridad

Configuración de permisos de base de datos

Seguridad en modo HTTP

🚀 Scripts NPM

📝 Variables de entorno

❗ Preguntas frecuentes

1. Puerto en uso

2. Error de conexión

3. Pérdida de sesión

4. Error de conexión cerrada

📦 Historial de versiones

v4.0.5 (2025-12-09) - Optimización del pool de conexiones

v4.0.0 (2025-12-09) - Nueva arquitectura

v3.x - Versiones anteriores

📞 Soporte y comentarios

🔧 Solución de problemas

Problema: error ERR_MODULE_NOT_FOUND

Problema: flujo SSE interrumpido

Problema: advertencia de vulnerabilidad de seguridad

Problema: puerto en uso

Obtener más ayuda

📄 Licencia

Problema: error `ERR_MODULE_NOT_FOUND`