mcp-mysql-client

MySQL MCP

MySQL MCP conecta una aplicación de IA a una única base de datos MySQL o MariaDB: ver la estructura, hacer preguntas a los datos en lenguaje natural, entender una consulta lenta — y, si tú mismo lo has permitido, modificar datos.

El servidor está vinculado a una única base de datos: esta se define mediante configuración, y ninguna herramienta puede acceder a otra. Por defecto, solo está disponible la lectura.

• 6 herramientas. Conexión y permisos, lista de tablas, estructura de tabla, consulta de lectura, plan de consulta, consulta de modificación.
• El tipo de consulta lo determina el servidor. El SQL se analiza antes de la conexión: DELETE en la herramienta de lectura será rechazado, incluso si los permisos de escritura están habilitados.
• La lectura no puede escribir. Las consultas de lectura se ejecutan dentro de START TRANSACTION READ ONLY — la escritura será rechazada por el propio MySQL, incluso si alguien engaña al análisis SQL.
• La respuesta no desbordará el contexto. Las filas se leen en flujo y se cortan en el límite, no se descargan completas; en la respuesta hay un indicador honesto truncated.
• Permisos solo desde fuera. INSERT, UPDATE y DELETE se activan mediante variables de entorno y requieren reinicio — no se pueden obtener desde el diálogo. DDL no está disponible nunca.

Comience con una consulta que solo lea datos:

Muestra la estructura de la base de datos y calcula cuántos registros aparecieron en la última semana.

---

Inicio rápido

Claude Code:

claude mcp add mysql-myapp \
  -e MYSQL_HOST=db.example.com \
  -e MYSQL_USER=myapp_ro \
  -e MYSQL_PASS='пароль' \
  -e MYSQL_DB=myapp \
  -e MYSQL_SSL=true \
  -- npx -y mcp-mysql-client

O en .mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "mysql-myapp": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-client"],
      "env": {
        "MYSQL_HOST": "db.example.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "myapp_ro",
        "MYSQL_PASS": "пароль",
        "MYSQL_DB": "myapp",
        "MYSQL_SSL": "true"
      }
    }
  }
}

Un servidor — una base de datos. ¿Necesitas varias bases? Añade varias entradas con sus propias credenciales; así los permisos permanecen aislados, y el servidor conectado a la base de pruebas no ve físicamente la de producción.

Qué se puede encargar

Consulta	Qué hace el servidor
«¿Qué hay en esta base de datos?»	list_tables — tablas, tamaños, estimaciones de número de filas
«¿Cómo está estructurada la tabla orders?»	describe_table — columnas, índices, claves foráneas en ambas direcciones
«¿Cuántos pedidos hay de julio y por qué importe?»	query — SELECT con agregación
«¿Por qué esta consulta es lenta?»	explain — plan, índices, estimación de filas
«¿Con qué usuario estoy conectado y qué puedo hacer?»	server_info — base de datos, usuario, GRANT, límites del servidor
«Marca el estado de los pedidos cancelados»	execute — solo si ALLOW_UPDATE_OPERATION=true

Qué puede cambiar

Por defecto — nada: el servidor arranca en modo solo lectura. La escritura se activa operación por operación:

"ALLOW_INSERT_OPERATION": "true",
"ALLOW_UPDATE_OPERATION": "true",
"ALLOW_DELETE_OPERATION": "false"

Lo que sigue siendo imposible:

• DDL — CREATE, ALTER, DROP, TRUNCATE, RENAME — bajo ninguna configuración.
• Cambio de base de datos, SET, CALL, PREPARE, LOAD DATA, bloqueos, GRANT y otras cosas que cambian el significado de la siguiente consulta o ejecutan texto no verificado.
• SELECT ... INTO OUTFILE — escritura de archivos en el servidor de la base de datos.
• UPDATE y DELETE sin WHERE — requieren confirmación explícita allow_full_table=true en la llamada.
• Varias instrucciones en una sola llamada — se ejecuta exactamente una.

Los permisos de MySQL son una restricción adicional por encima de esto. El permiso ALLOW_UPDATE_OPERATION no añade nada a un usuario que no tenga GRANT UPDATE. Práctica recomendada: un usuario separado con permisos mínimos, no root.

Variables de entorno

Variable	Por defecto	Propósito
MYSQL_HOST	127.0.0.1	Host del servidor
MYSQL_PORT	3306	Puerto
MYSQL_SOCKET_PATH	—	Socket Unix en lugar de host/puerto
MYSQL_USER	—	Usuario (obligatorio)
MYSQL_PASS	—	Contraseña (sinónimo de MYSQL_PASSWORD)
MYSQL_PASS_FILE	—	Leer la contraseña desde un archivo en lugar de una variable
MYSQL_DB	—	Base de datos (obligatorio, sinónimo de MYSQL_DATABASE)
MYSQL_SSL	false	Exigir TLS
MYSQL_SSL_CA	—	Ruta al certificado raíz; por sí solo activa TLS
MYSQL_SSL_REJECT_UNAUTHORIZED	true	Verificar el certificado del servidor
ALLOW_INSERT_OPERATION	false	Permitir INSERT
ALLOW_UPDATE_OPERATION	false	Permitir UPDATE
ALLOW_DELETE_OPERATION	false	Permitir DELETE
MYSQL_MAX_ROWS	1000	Límite de filas en una sola respuesta
MYSQL_TIMEOUT_MS	30000	Tiempo de espera de consulta
MYSQL_CONNECT_TIMEOUT_MS	10000	Tiempo de espera de conexión
MYSQL_POOL_SIZE	3	Conexiones en el pool
MYSQL_MAX_RETRIES	2	Reintentos ante caídas de conexión y bloqueos mutuos
MYSQL_READ_ONLY_TX	true	Ejecutar lecturas en transacción de solo lectura
ASKADS_TELEMETRY	—	0 desactiva las estadísticas anónimas de arranques

La contraseña en la configuración del cliente MCP está en texto plano. MYSQL_PASS_FILE permite mantenerla en un archivo con los permisos adecuados.

Migración desde @benborla29/mcp-server-mysql

Los nombres de las variables coinciden, por lo que basta con reemplazar el paquete en el comando de arranque:

-  "args": ["-y", "@benborla29/mcp-server-mysql"]
+  "args": ["-y", "mcp-mysql-client"]

Qué cambiará en el comportamiento:

• MYSQL_DB es obligatorio — el servidor siempre está vinculado a una única base de datos;
• las respuestas están limitadas a MYSQL_MAX_ROWS y se marcan con truncated;
• DDL no está disponible incluso con permisos de escritura habilitados;
• UPDATE/DELETE sin WHERE requieren confirmación en la llamada;
• el conjunto de herramientas es diferente: query, execute, explain, list_tables, describe_table, server_info.

Diagnóstico

Lo primero — server_info: mostrará a qué está conectado el servidor, qué permisos tiene el usuario de MySQL y qué limitaciones están activadas.

Síntoma	Causa
errno 1045	MYSQL_USER / MYSQL_PASS incorrectos
errno 1044	El usuario existe, pero no tiene permisos sobre la base de datos
errno 1142	Falta GRANT para la operación o la tabla — ALLOW_* no ayudará aquí
errno 3159	El servidor exige TLS: MYSQL_SSL=true
ECONNREFUSED / ETIMEDOUT	Host, puerto, firewall o VPN no levantada
ER_NOT_SUPPORTED_AUTH_MODE	Se necesita TLS para caching_sha2_password
El servidor no se conecta	El error de configuración se ve directamente en el diálogo: el servidor arranca incluso sin credenciales y explica qué falta

Documentación técnica

• Herramientas — parámetros y respuestas
• Desarrollo — compilación, pruebas, verificación en vivo
• Publicación — lanzamiento en npm y el registro MCP
• CLAUDE.md — estructura del repositorio para agentes de IA

Licencia

MIT