MySQL

Integración de base de datos MySQL con controles de acceso configurables e inspección de esquemas.

GitHub
1.4k
Prueba este MCPPatrocinado

Documentación

Tests PyPI - Downloads AgentAudit Safe

Servidor MCP de MySQL

Una implementación del Protocolo de Contexto de Modelo (MCP) que permite la interacción segura con bases de datos MySQL. Este componente de servidor facilita la comunicación entre aplicaciones de IA (hosts/clientes) y bases de datos MySQL, haciendo la exploración y el análisis de bases de datos más seguros y estructurados a través de una interfaz controlada.

Nota: El Servidor MCP de MySQL admite tanto el modo de entrada/salida estándar (STDIO) como el modo de transporte HTTP Streamable (SSE). El modo SSE se recomienda para implementaciones remotas o autoalojadas.

Opciones de implementación

  • Alojado — Fronteir AI ejecuta el servidor por ti; no se requiere configuración local.
  • Local — Smithery instala y ejecuta el servidor en tu propia máquina.

Características

  • Listar tablas MySQL disponibles como recursos
  • Leer el contenido de las tablas
  • Ejecutar consultas SQL con manejo adecuado de errores
  • Modo multi-base de datos (Opcional MYSQL_DATABASE)
  • Soporte de transporte SSE/HTTP (MCP_TRANSPORT=sse)
  • Soporte de túneles SSH
  • Información completa del esquema
  • Muestreo de datos de tablas
  • Acceso seguro a la base de datos mediante variables de entorno
  • Registro (logging) completo

Instalación

Instalación manual

pip install mysql-mcp-server

Instalación mediante Smithery

Para instalar el Servidor MCP de MySQL para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Instalación mediante la CLI de Claude Code

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Instalación mediante la CLI de Autohand Code

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

Agrega --scope project después de mcp add para mantener el registro en el espacio de trabajo actual. Consulta Autohand Code para obtener detalles actuales de la CLI.

Configuración

Establece las siguientes variables de entorno:

MYSQL_HOST=localhost     # Database host
MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not specified)
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode

# Advanced Configuration
MYSQL_SSL_MODE=DISABLED  # DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # Timeout in seconds

# Connection behaviour (Optional)
MYSQL_SQL_MODE=TRADITIONAL           # SQL mode applied to the connection (default: TRADITIONAL)

# Compatibility (Optional)
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # e.g., mysql_native_password for older MySQL versions
MYSQL_USE_PURE=false     # Force the pure-Python connector (default: false)
MYSQL_RAISE_ON_WARNINGS=false        # Raise on SQL warnings (default: false)

# SSE Transport (Optional)
MCP_TRANSPORT=stdio      # stdio or sse
MCP_SSE_HOST=0.0.0.0     # Listen on all interfaces (required for Docker/hosting)
PORT=8000                # HTTP port (fallback for MCP_SSE_PORT)
MCP_SSE_ALLOWED_HOSTS=   # Comma-separated allowed Host headers (default: localhost:{port},127.0.0.1:{port})

# SSH Tunneling (Optional)
MYSQL_SSH_ENABLE=false   # Set to true to enable
MYSQL_SSH_HOST=          # SSH jump host
MYSQL_SSH_PORT=22        # SSH port
MYSQL_SSH_USER=          # SSH username
MYSQL_SSH_KEY_PATH=      # Path to SSH private key
MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

Carga del archivo .env

Al iniciar, el servidor carga automáticamente un archivo .env mediante python-dotenv, por lo que para uso local simplemente puedes:

cp .env.example .env   # then edit with your credentials

El archivo se lee desde el directorio de trabajo del proceso (y directorios padre), lo que funciona cuando ejecutas el servidor tú mismo desde la carpeta del proyecto.

⚠️ Claude Code / Claude Desktop: estos hosts inician el servidor desde su propio directorio de trabajo, por lo que el .env del proyecto no se encontrará y verás Missing required database configuration. Coloca tus valores de MYSQL_* en el bloque env de la configuración MCP (que se muestra en la sección de Uso a continuación) en lugar de depender de .env.

Modo multi-base de datos

Cuando MYSQL_DATABASE no está configurado, el servidor opera en modo multi-base de datos:

  • list_resources devuelve todas las bases de datos de usuario (las bases de datos del sistema se filtran)
  • Usa nombres de tabla completamente calificados como mydb.mytable en consultas SQL
  • Nota: Solo se admiten sentencias SQL individuales. No se admiten consultas de múltiples sentencias (por ejemplo, USE db; SELECT ...).

Herramientas disponibles

execute_sql

Ejecuta cualquier consulta SQL estándar.

  • Argumentos: query (cadena)
  • Características: Admite SELECT, SHOW, DESCRIBE y DML (INSERT, UPDATE, DELETE). Las operaciones DML se marcan con una advertencia de destructividad.
  • Limitación: Solo sentencias individuales. No se admiten consultas de múltiples sentencias.
  • Entre bases de datos: Usa la notación database.table para consultar cualquier base de datos independientemente de la configuración de MYSQL_DATABASE.

get_schema_info

Proporciona metadatos detallados sobre las estructuras de la base de datos.

  • Argumentos: table_name (cadena opcional)
  • Salida: Nombres de columnas, tipos, nulabilidad, valores predeterminados y comentarios.
  • Entre bases de datos: Pasa database.table para consultar una tabla fuera de MYSQL_DATABASE; los nombres simples usan la base de datos configurada.
  • Reglas de identificadores: Los nombres deben contener solo caracteres alfanuméricos, guiones bajos y $ (se permiten puntos como separador entre nombres de base de datos y tabla).

get_table_sample

Obtiene una muestra representativa de datos.

  • Argumentos: table_name (cadena), limit (entero opcional, máximo 20)
  • Caso de uso: Comprender rápidamente los formatos y el contenido de los datos sin recuperar conjuntos de resultados grandes.
  • Entre bases de datos: Pasa database.table para muestrear una tabla fuera de MYSQL_DATABASE; los nombres simples usan la base de datos configurada.
  • Reglas de identificadores: Los nombres deben contener solo caracteres alfanuméricos, guiones bajos y $ (se permiten puntos como separador entre nombres de base de datos y tabla).

Prompts disponibles

Además de las herramientas, el servidor expone prompts MCP — flujos de trabajo guiados de múltiples pasos que un cliente puede lanzar bajo demanda. En Claude Code aparecen como comandos de barra (/mcp__<server>__<prompt>); en Claude Desktop aparecen en el menú de prompts (+).

PromptArgumentosDescripción
explore_database(ninguno)Explorar sistemáticamente la base de datos: descubrir tablas disponibles, inspeccionar sus esquemas, muestrear los datos y resumir lo que hay.
analyze_tabletable_name (obligatorio)Análisis profundo de una tabla específica: recuperar su esquema, muestrear sus datos y sugerir consultas útiles. Acepta la notación database.table para búsquedas entre bases de datos.

Ejemplo (Claude Code):

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

Ambos prompts orquestan las herramientas existentes get_schema_info y get_table_sample; explore_database también utiliza el listado de recursos para enumerar tablas.

Uso

Con Claude Desktop

Agrega esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mysql_mcp_server",
        "run",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Para ejemplos más detallados y orientación específica para agentes, consulta MCP_USECASES.md.

Con Visual Studio Code

Agrega esto a tu mcp.json:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mysql-mcp-server",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Nota: Será necesario instalar uv para que esto funcione

Depuración con MCP Inspector

Aunque el Servidor MCP de MySQL no está diseñado para ejecutarse de forma independiente o directamente desde la línea de comandos con Python, puedes usar MCP Inspector para depurarlo.

MCP Inspector proporciona una forma conveniente de probar y depurar tu implementación MCP:

# Install dependencies
pip install -r requirements.txt
# Use the MCP Inspector for debugging (do not run directly with Python)

El Servidor MCP de MySQL está diseñado para integrarse con aplicaciones de IA como Claude Desktop y no debe ejecutarse directamente como un programa Python independiente.

Desarrollo

# Clone the repository
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
# Install development dependencies
pip install -r requirements-dev.txt
# Copy the example config and edit with your credentials
cp .env.example .env
# Edit .env with your MySQL connection details
# Run tests
pytest

Consideraciones de seguridad

  • Validación de identificadores: Los nombres de tablas y bases de datos pasados a get_schema_info y get_table_sample se validan contra una lista blanca estricta (solo alfanuméricos, guiones bajos y $; se permite un solo punto como separador de database.table). Otros caracteres especiales se rechazan para prevenir la inyección SQL.

  • Acceso cifrado: Soporte completo para SSL/TLS y túneles SSH para conexiones remotas seguras.

  • Privacidad de registros: Las contraseñas y claves privadas SSH se enmascaran automáticamente en los registros del servidor.

  • Mínimo privilegio: Usa siempre un usuario MySQL dedicado con los permisos mínimos requeridos.

  • El transporte SSE no tiene autenticación incorporada. El servidor SSE se vincula a 0.0.0.0 de forma predeterminada y acepta conexiones sin credenciales. Si lo expones más allá de localhost, colócalo detrás de un proxy inverso (nginx, Caddy, Traefik) que aplique autenticación. Ejemplo con nginx y autenticación básica HTTP:

    location /sse {
    auth_basic "MCP";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_buffering off;
}
location /messages/ {
    auth_basic "MCP";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
}

    Establece MCP_SSE_HOST=127.0.0.1 para que el servidor solo escuche en loopback y el proxy sea el único punto de entrada público. Establece MCP_SSE_ALLOWED_HOSTS al nombre de host público al que tu proxy reenvía (por ejemplo, MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

Consulta SECURITY.md para obtener una guía completa sobre cómo asegurar tu implementación.

Mejores prácticas de seguridad

Esta implementación MCP requiere acceso a la base de datos para funcionar. Por seguridad:

  1. Crea un usuario MySQL dedicado con permisos mínimos
  2. Nunca uses credenciales de root ni cuentas administrativas
  3. Restringe el acceso a la base de datos solo a las operaciones necesarias
  4. Habilita el registro con fines de auditoría
  5. Revisiones de seguridad periódicas del acceso a la base de datos

Consulta la Guía de configuración de seguridad de MySQL para obtener instrucciones detalladas sobre:

  • Crear un usuario MySQL restringido
  • Establecer permisos apropiados
  • Monitorear el acceso a la base de datos
  • Mejores prácticas de seguridad

⚠️ IMPORTANTE: Sigue siempre el principio de mínimo privilegio al configurar el acceso a la base de datos.

Licencia

Licencia MIT: consulta el archivo LICENSE para obtener detalles.

Contribuciones

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/amazing-feature)
  3. Realiza tus cambios (git commit -m 'Add some amazing feature')
  4. Envía los cambios a la rama (git push origin feature/amazing-feature)
  5. Abre una Solicitud de Extracción (Pull Request)