Metadata-Version: 2.4
Name: mcp-mysql-server-bruno
Version: 1.1.0
Summary: Servidor MCP para MySQL - Model Context Protocol
Author-email: Bruno Izaguirre <bruno.izagumart@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/mcp-mysql-server
Project-URL: Repository, https://github.com/yourusername/mcp-mysql-server
Project-URL: Issues, https://github.com/yourusername/mcp-mysql-server/issues
Keywords: mysql,mcp,database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mysql-connector-python<9.0.0,>=8.1.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: fastmcp>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.4.0; extra == "dev"

# MCP MySQL Server

Servidor MySQL que implementa el Model Context Protocol (MCP) para integración con LLMs vía stdio.

## Características

- ✅ Consultas de lectura (SELECT, SHOW, DESCRIBE, EXPLAIN)
- ✅ Operaciones de escritura (INSERT, UPDATE, DELETE)
- ✅ Llamadas a procedimientos almacenados
- ✅ Exploración de metadatos (esquemas, tablas, columnas)
- ✅ Modo READ_ONLY configurable
- ✅ Pool de conexiones
- ✅ Limitador de filas en consultas
- ✅ Validación de SQL básica
- ✅ Comunicación stdio para MCP

## Requisitos

- Python 3.10+ (requerido por fastmcp)
- MySQL 5.7+ / MariaDB 10.2+

## Instalación

1. Crear entorno virtual:
```powershell
python -m venv venv
.\venv\Scripts\Activate.ps1
```

2. Instalar dependencias:
```powershell
pip install -r requirements.txt
```

3. Configurar variables de entorno:
```bash
cp .env.example .env
# Editar .env con tus credenciales
```

## Configuración

### Variables de entorno (.env)

**DATABASE_URL** (requerido):
```
DATABASE_URL=mysql://usuario:password@host:puerto/base_datos?sslmode=disable
```

**Importante**: Si tu contraseña contiene caracteres especiales (@, #, %, etc.), debes URL-encodearlos:
- `@` → `%40`
- `#` → `%23`
- `&` → `%26`
- `:` → `%3A`
- `/` → `%2F`

Ejemplo:
```
# Password: P@ss#123
DATABASE_URL=mysql://user:P%40ss%23123@localhost:3306/mydb?sslmode=disable
```

**READ_ONLY** (opcional, default: true):
- `true` = Solo consultas de lectura
- `false` = Permite escritura y procedimientos

**Otras variables**:
- `DB_POOL_SIZE`: Tamaño del pool de conexiones (default: 5)
- `DB_POOL_NAME`: Nombre del pool (default: mcp_mysql_pool)
- `PORT`: Puerto del servidor (default: 8000)
- `HOST`: Host del servidor (default: 0.0.0.0)

## Ejecutar

### Modo 1: Servidor HTTP (FastAPI)

Para API REST tradicional:

```powershell
## Ejecutar

### Modo interactivo (pruebas):

```powershell
python mcp_server.py
```

### Configuración en Claude Desktop:

Edita `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["c:/Users/bruno.izaguirre/Documents/mysqlMCP/mcp_server.py"],
      "env": {
        "DATABASE_URL": "mysql://user:pass@host:3306/dbname?sslmode=disable",
        "READ_ONLY": "true"
      }
    }
  }
}
```

### Configuración en LibreChat:

```json
{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["c:/ruta/al/proyecto/mcp_server.py"],
      "env": {
        "DATABASE_URL": "mysql://user:pass@host:3306/dbname?sslmode=disable",
        "READ_ONLY": "true"
      }
    }
  }
}
```

## Herramientas MCP disponibles

El servidor expone estas herramientas para interactuar con MySQL:

- `query_database(sql, params, limit)` - Ejecutar consultas SELECT
- `execute_statement(sql, params)` - Ejecutar INSERT/UPDATE/DELETE (requiere READ_ONLY=false)
- `call_procedure(procedure, params)` - Llamar procedimientos almacenados
- `list_tables(schema)` - Listar todas las tablas
- `get_table_schema(table, schema)` - Ver columnas de una tabla
- `list_schemas()` - Listar bases de datos disponibles
```bash
POST /execute
{
  "sql": "INSERT INTO usuarios (nombre) VALUES (?)",
  "params": ["Juan"]
}
## Seguridad

⚠️ **Importante**:
- Las credenciales de base de datos deben estar en `.env` (nunca en git)
- En producción configura `READ_ONLY=true` si no necesitas escritura
- Valida permisos de usuario MySQL según tus necesidades
- El servidor usa conexión stdio (solo accesible por el proceso padre)

## Testing

Prueba el servidor ejecutándolo directamente:

```powershell
python mcp_server.py
```

El servidor se comunicará vía stdio. Para pruebas, úsalo desde un cliente MCP como Claude Desktop.

## Troubleshooting

### Error: "Se requiere la variable de entorno DATABASE_URL"
- Verifica que `.env` existe y contiene `DATABASE_URL`
- Las variables se cargan automáticamente con `python-dotenv`

### Error: "No module named 'fastmcp'"
- Ejecuta: `pip install -r requirements.txt`

### Error de conexión SSL
- Usa `?sslmode=disable` en DATABASE_URL para desarrollo local
- Para producción, configura certificados SSL apropiados

### Error: "Access denied for user"
- Verifica que el usuario MySQL tenga permisos desde tu IP
- El administrador debe ejecutar: `GRANT ALL ON database.* TO 'user'@'%'`

### Error: "No se permiten punto y coma"
- El servidor bloquea múltiples sentencias SQL por seguridad
- Ejecuta una sentencia a la vez

## Licencia

MIT
