npm package: @kesquivelt.atlas/mysql-mcp-server
Description: Complete MCP server for MySQL with full DDL, DML and CRUD operations - by Kevin Esquivel
Author: Kevin Esquivel
Latest version: 1.0.4

# 🐬 MCP MySQL Server

Un servidor **MCP (Model Context Protocol)** completo y robusto para MySQL que proporciona acceso total a operaciones DDL, DML, stored procedures y administración de base de datos directamente desde **Claude Desktop**.

> **Desarrollado por Kevin Esquivel - Especialista en Desarrollo de IA**  
> 📱 Consultas y soporte: WhatsApp [+502 37667896](https://wa.me/50237667896)

---

## Características

### ✅ Operaciones Completas Soportadas

- **Conexión y Gestión de Base de Datos**
  - Conectar/desconectar a MySQL
  - Listar, crear, eliminar y cambiar bases de datos
  
- **Operaciones DDL (Data Definition Language)**
  - Crear, alterar y eliminar tablas
  - Gestión completa de índices
  - Gestión de columnas (agregar, modificar, eliminar)
  - Truncar tablas

- **Operaciones CRUD Completas**
  - SELECT con JOINs, WHERE, ORDER BY, LIMIT
  - INSERT (simple y bulk)
  - UPDATE con WHERE y LIMIT
  - DELETE con WHERE y LIMIT

- **Stored Procedures y Funciones**
  - Listar, crear y eliminar procedures/functions
  - Ejecutar stored procedures
  - Obtener definiciones de procedures

- **Herramientas Avanzadas**
  - Ejecución de SQL crudo
  - Inspección de estructura de tablas
  - Gestión de índices
  - Conexiones seguras con SSL

## Instalación

1. Clona o descarga el proyecto
2. Instala las dependencias:

```bash
cd mcp-mysql-server
npm install
```

3. Compila el proyecto:

```bash
npm run build
```

## ⚙️ Configuración en Claude Desktop

Agrega la siguiente configuración a tu archivo `claude_desktop_config.json`:

### Opción 1: Usando el servidor compilado (Recomendado)
```json
{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-server",
      "args": [],
      "env": {}
    }
  }
}
```

### Opción 2: Usando el servidor directo (Desarrollo)
```json
{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": [
        "C:\\ruta\\a\\tu\\proyecto\\mcp-mysql-server\\simple-server.js"
      ],
      "cwd": "C:\\ruta\\a\\tu\\proyecto\\mcp-mysql-server"
    }
  }
}
```

> **Nota**: Reemplaza `C:\\ruta\\a\\tu\\proyecto\\` con la ruta real donde clonaste este proyecto.

### Ubicación del archivo de configuración:

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

## 🚀 Uso Completo

Una vez configurado, todas las herramientas MySQL estarán disponibles directamente en **Claude Desktop**. Solo necesitas usar el lenguaje natural para interactuar con tu base de datos.

### 🔌 1. Conectar a MySQL

**Ejemplo natural en Claude:**
> "Conéctate a mi base de datos MySQL usando localhost, puerto 3306, usuario root y contraseña MiPassword123"

**Parámetros técnicos:**
```json
{
  "host": "localhost",
  "port": 3306,
  "user": "root", 
  "password": "tu_password",
  "database": "mi_base_datos",  // opcional
  "ssl": false,                 // opcional
  "charset": "utf8mb4"         // opcional
}
```

### 🗃️ 2. Gestión de Bases de Datos

**Ejemplos naturales en Claude:**
> "Lista todas las bases de datos disponibles"
> "Crea una nueva base de datos llamada 'mi_proyecto'"
> "Cambia a la base de datos 'atlas_test'"
> "Elimina la base de datos 'proyecto_viejo'"

**Operaciones disponibles:**
- ✅ **Listar** bases de datos existentes
- ✅ **Crear** nuevas bases de datos con charset personalizado
- ✅ **Eliminar** bases de datos (con confirmación IF EXISTS)
- ✅ **Cambiar** de base de datos activa

### 📋 3. Gestión de Tablas

**Ejemplos naturales en Claude:**
> "Lista todas las tablas de la base de datos actual"
> "Crea una tabla llamada 'usuarios' con columnas id, nombre, email y fecha_registro"
> "Muéstrame la estructura de la tabla 'administradores'"
> "Elimina la tabla 'datos_temporales'"

**Capacidades avanzadas:**
- ✅ **Crear tablas** con columnas personalizadas, claves primarias y AUTO_INCREMENT
- ✅ **Describir estructura** completa de tablas existentes
- ✅ **Listar todas las tablas** con información detallada
- ✅ **Eliminar tablas** de forma segura
- ✅ **Especificar tipos de datos** MySQL completos (INT, VARCHAR, TIMESTAMP, etc.)
- ✅ **Configurar defaults** y restricciones NOT NULL

### 📊 4. Operaciones CRUD Completas

**Ejemplos naturales en Claude:**
> "Muéstrame todos los registros de la tabla administradores"
> "Inserta un nuevo administrador: nombre 'Carlos López', cargo 'CTO'"
> "Actualiza el cargo de Kevin Esquivel a 'Lead IA Developer'"
> "Elimina todos los usuarios inactivos"

**SELECT Avanzado:**
- ✅ **Consultas básicas** con columnas específicas
- ✅ **Filtrado WHERE** con condiciones complejas
- ✅ **Ordenamiento ORDER BY** ascendente/descendente
- ✅ **Paginación** con LIMIT y OFFSET
- ✅ **Joins entre tablas** para consultas relacionales

**INSERT Masivo:**
- ✅ **Inserción múltiple** de registros en una sola operación
- ✅ **Manejo de duplicados** con ON DUPLICATE KEY UPDATE
- ✅ **AUTO_INCREMENT** automático para claves primarias

**UPDATE Preciso:**
- ✅ **Actualización condicional** con WHERE
- ✅ **Límite de registros** afectados con LIMIT
- ✅ **Múltiples columnas** en una sola operación

**DELETE Seguro:**
- ✅ **Eliminación condicional** para evitar borrado accidental
- ✅ **Límite de registros** para operaciones masivas controladas

### ⚙️ 5. Stored Procedures y Funciones

**Ejemplos naturales en Claude:**
> "Lista todos los stored procedures de la base de datos"
> "Crea un stored procedure llamado 'obtener_admin' que reciba un ID y devuelva los datos del administrador"
> "Ejecuta el stored procedure 'obtener_admin' con el parámetro 1"
> "Elimina el stored procedure 'procedimiento_viejo'"

**Capacidades Profesionales:**
- ✅ **Crear stored procedures** con parámetros IN, OUT, INOUT
- ✅ **Crear funciones MySQL** con valores de retorno
- ✅ **Ejecutar procedures** con parámetros dinámicos
- ✅ **Listar procedures** existentes con metadatos
- ✅ **Eliminar procedures** de forma segura
- ✅ **Lógica de negocio** compleja en la base de datos

### 🛠️ 6. SQL Crudo y Consultas Personalizadas

**Ejemplos naturales en Claude:**
> "Ejecuta esta consulta SQL: SELECT * FROM administradores WHERE cargo LIKE '%Dev%'"
> "Corre una consulta que me muestre el conteo de administradores por cargo"
> "Ejecuta un INNER JOIN entre administradores y sus proyectos"

**Poder Total de MySQL:**
- ✅ **Cualquier consulta SQL** sin restricciones
- ✅ **Consultas complejas** con múltiples JOINs
- ✅ **Funciones agregadas** (COUNT, SUM, AVG, etc.)
- ✅ **Subqueries** y consultas anidadas
- ✅ **Parámetros preparados** para seguridad
- ✅ **DDL completo** (CREATE, ALTER, DROP)
- ✅ **Transacciones** y operaciones atómicas

## 🔧 Herramientas Disponibles (19 herramientas completas)

### 🔌 Conexión y Gestión
| Herramienta | Descripción | Ejemplo de uso |
|-------------|-------------|----------------|
| `connect` | Conectar a MySQL | "Conéctate a localhost con usuario root" |
| `disconnect` | Desconectar de MySQL | "Desconéctate de la base de datos" |

### 🗃️ Bases de Datos
| Herramienta | Descripción | Ejemplo de uso |
|-------------|-------------|----------------|
| `list_databases` | Listar bases de datos | "Muéstrame todas las bases de datos" |
| `create_database` | Crear base de datos | "Crea una BD llamada 'mi_proyecto'" |
| `drop_database` | Eliminar base de datos | "Elimina la BD 'proyecto_viejo'" |
| `use_database` | Cambiar base de datos activa | "Cambia a la BD 'atlas_test'" |

### 📋 Tablas
| Herramienta | Descripción | Ejemplo de uso |
|-------------|-------------|----------------|
| `list_tables` | Listar tablas | "Lista todas las tablas" |
| `describe_table` | Describir estructura | "Describe la tabla 'administradores'" |
| `create_table` | Crear tabla | "Crea tabla 'usuarios' con id y nombre" |
| `drop_table` | Eliminar tabla | "Elimina la tabla 'temp_data'" |

### 📊 CRUD Completo
| Herramienta | Descripción | Ejemplo de uso |
|-------------|-------------|----------------|
| `select` | Consulta SELECT | "Muestra todos los administradores" |
| `insert` | Insertar datos | "Inserta un nuevo usuario" |
| `update` | Actualizar datos | "Actualiza el cargo de Kevin" |
| `delete` | Eliminar datos | "Elimina usuarios inactivos" |

### ⚙️ Stored Procedures
| Herramienta | Descripción | Ejemplo de uso |
|-------------|-------------|----------------|
| `list_stored_procedures` | Listar procedures | "Lista todos los procedures" |
| `create_stored_procedure` | Crear procedure | "Crea un procedure para obtener usuario" |
| `drop_stored_procedure` | Eliminar procedure | "Elimina el procedure 'old_proc'" |
| `call_stored_procedure` | Ejecutar procedure | "Ejecuta el procedure con ID 123" |

### 🛠️ Utilidades Avanzadas
| Herramienta | Descripción | Ejemplo de uso |
|-------------|-------------|----------------|
| `execute_sql` | SQL crudo completo | "Ejecuta: SELECT COUNT(*) FROM users" |

## 🔒 Seguridad y Mejores Prácticas

- ✅ **Conexiones SSL** habilitadas por defecto
- ✅ **Prepared statements** para prevenir SQL injection
- ✅ **Parámetros validados** en todas las operaciones  
- ✅ **Credenciales seguras** - nunca hardcodear passwords
- ⚠️ **Usuarios específicos** - evitar usar root en producción
- ⚠️ **Permisos mínimos** - dar solo los accesos necesarios

## 🚀 Instalación de MySQL Server

### Windows (Recomendado: MySQL Community Server)
1. Descargar de: https://dev.mysql.com/downloads/mysql/
2. Instalar con configuración por defecto (puerto 3306)
3. Crear contraseña para usuario `root`
4. Probar conexión: `mysql -u root -p`

### Alternativa: XAMPP (Más fácil)
1. Descargar XAMPP: https://www.apachefriends.org/
2. Instalar y ejecutar
3. Iniciar MySQL desde XAMPP Control Panel
4. Usuario: `root`, Password: (vacío)

## 🛠️ Desarrollo y Contribución

```bash
# Instalar dependencias
npm install

# Desarrollo en tiempo real
npm run dev

# Compilar proyecto
npm run build

# Ejecutar servidor compilado
npm start
```

## 📞 Soporte y Contacto

**Kevin Esquivel - Especialista en Desarrollo de IA**
- 📱 WhatsApp: [+502 37667896](https://wa.me/50237667896)
- 💼 LinkedIn: Especializado en integración de IA y bases de datos
- 🚀 Disponible para proyectos personalizados y consultoría

---

## 📄 Licencia

MIT License - Libre para uso comercial y personal

> **Desarrollado con ❤️ en Guatemala 🇬🇹**