MySQL MCP Server

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

Nota: MySQL MCP Server es compatible con los modos de transporte de entrada/salida estándar (STDIO) y HTTP transmisible (SSE). Se recomienda el modo SSE para implementaciones remotas o autogestionadas.

Opciones de implementación

• Gestionado — Fronteir AI ejecuta el servidor por ti, sin configuración local.

• Local — Smithery instala y ejecuta el servidor en tu propia máquina.

Related MCP server: MCP MySQL Server

Características

• Enumera las tablas MySQL disponibles como recursos

• Lee el contenido de las tablas

• Ejecuta consultas SQL con un manejo de errores robusto

• Modo multi-base de datos (MYSQL_DATABASE opcional)

• Soporte de transporte SSE/HTTP (MCP_TRANSPORT=sse)

• Soporte de túneles SSH

• Información completa del esquema de tablas

• Muestreo de datos de tablas

• Acceso seguro a la base de datos mediante variables de entorno

• Registro de auditoría completo

Instalación

Instalación manual

pip install mysql-mcp-server

Instalación con Smithery

Instala automáticamente MySQL MCP Server para Claude Desktop con Smithery:

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

Instalación con Claude Code CLI

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

Instalación con Autohand Code CLI

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

Añade --scope project después de mcp add para conservar el registro en el espacio de trabajo actual. Consulta Autohand Code para obtener más detalles sobre la CLI.

Configuración

Establece las siguientes variables de entorno:

MYSQL_HOST=localhost     # 数据库主机
MYSQL_PORT=3306         # 可选：数据库端口（不指定时默认 3306）
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # 可选：留空则进入多数据库模式

# 高级配置
MYSQL_SSL_MODE=DISABLED  # DISABLED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # 超时时间（秒）

# 连接行为（可选）
MYSQL_SQL_MODE=TRADITIONAL           # 连接所应用的 SQL mode（默认：TRADITIONAL）

# 兼容性（可选）
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # 例如旧版 MySQL 使用 mysql_native_password
MYSQL_USE_PURE=false     # 强制使用纯 Python 连接器（默认：false）
MYSQL_RAISE_ON_WARNINGS=false        # 出现 SQL 警告时抛出异常（默认：false）

# SSE 传输（可选）
MCP_TRANSPORT=stdio      # stdio 或 sse
MCP_SSE_HOST=0.0.0.0     # 监听所有网卡（Docker/托管部署需要）
PORT=8000                # HTTP 端口（MCP_SSE_PORT 的回退值）
MCP_SSE_ALLOWED_HOSTS=   # 逗号分隔的允许 Host 头（默认：localhost:{port},127.0.0.1:{port}）

# SSH 隧道（可选）
MYSQL_SSH_ENABLE=false   # 设为 true 启用
MYSQL_SSH_HOST=          # SSH 跳板机
MYSQL_SSH_PORT=22        # SSH 端口
MYSQL_SSH_USER=          # SSH 用户名
MYSQL_SSH_KEY_PATH=      # SSH 私钥路径
MYSQL_SSH_REMOTE_HOST=localhost # 从跳板机视角看的目标主机
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

Carga del archivo .env

El servidor carga automáticamente el archivo .env mediante python-dotenv al iniciarse. Para uso local, simplemente:

cp .env.example .env   # 然后填入你的凭据

El archivo se lee desde el directorio de trabajo del proceso (y sus directorios padre), por lo que funciona si inicias el servidor desde el directorio del proyecto.

⚠️ Claude Code / Claude Desktop: estos hosts inician el servidor desde sus propios directorios de trabajo, por lo que no encontrarán el .env del proyecto y verás Missing required database configuration. Escribe los valores de MYSQL_* en el bloque env de la configuración MCP (consulta «Uso» más abajo) en lugar de depender de .env.

Modo multi-base de datos

Cuando MYSQL_DATABASE no está definida, el servidor entra 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 completos en las consultas SQL, por ejemplo, mydb.mytable

• Nota: solo se admiten sentencias SQL individuales; no se admiten consultas de varias sentencias (por ejemplo, USE db; SELECT ...).

Página de administración y alias de bases de datos (modo SSE)

Inicia el servidor en modo SSE y abre la página de administración integrada para gestionar múltiples conexiones de base de datos, cada una con cuentas de lectura/escritura independientes:

# Windows PowerShell
$env:MCP_TRANSPORT="sse"; $env:MCP_SSE_PORT="8000"; python -m mysql_mcp_server
# Linux/macOS
MCP_TRANSPORT=sse MCP_SSE_PORT=8000 python -m mysql_mcp_server

Página de administración: http://127.0.0.1:8000/admin/ (solo acceso de bucle local: la API y la página de administración rechazan clientes no locales y cabeceras Host desconocidas; no la coloques detrás de un proxy inverso).

Cada alias se puede configurar con:

Los clientes se conectan mediante el alias: http://127.0.0.1:8000/sse?alias=db1 (se usa el alias predeterminado si se omite alias). Cuando config/databases.json no contiene ninguna entrada, las variables de entorno MYSQL_* originales siguen estando disponibles como respaldo de base de datos única compatible con versiones anteriores (en este modo, lectura y escritura comparten la misma cuenta).

Nota la diferencia con el modo multi-base de datos anterior: ese modo expone varios esquemas en una sola conexión; los alias, en cambio, gestionan varias conexiones, cada una con su propia cuenta y política de escritura.

Cómo se confirman las escrituras: el servidor clasifica cada sentencia en tres niveles (lectura / escritura / borrado). Las lecturas se ejecutan directamente con la cuenta de consulta; las escrituras y borrados activan el diálogo de elicitación de MCP mostrando el SQL completo: si se acepta, se ejecuta con la cuenta de operación; si se rechaza, se aborta. Si el cliente no admite la elicitación, el comportamiento de degradación lo determina la write_policy del alias (ver tabla anterior). Todos los intentos de escritura se registran en la lista de auditoría de la página de administración (en disco, logs/audit.log).

Herramientas disponibles

execute_sql

Ejecuta cualquier consulta SQL estándar.

• Parámetros: query (cadena)

• Función: admite SELECT, SHOW, DESCRIBE y DML (INSERT, UPDATE, DELETE). Las operaciones DML se marcan como potencialmente destructivas.

• Limitaciones: solo se admite una sentencia; no se admiten consultas de varias sentencias.

• Entre bases de datos: se puede consultar cualquier base de datos con la notación database.table, independientemente del valor de MYSQL_DATABASE.

get_schema_info

Proporciona metadatos detallados de la estructura de la base de datos.

• Parámetros: table_name (cadena opcional)

• Salida: nombres de columna, tipos, nulabilidad, valores predeterminados y comentarios.

• Entre bases de datos: pasa database.table para consultar bases de datos distintas de MYSQL_DATABASE; los nombres de tabla simples usan la base de datos configurada.

• Reglas de identificadores: los nombres solo pueden contener caracteres alfanuméricos, guiones bajos y $ (se permite un punto como separador de database.table).

get_table_sample

Obtiene una muestra representativa de datos.

• Parámetros: table_name (cadena), limit (entero opcional, máximo 20)

• Uso: comprende rápidamente el formato y el contenido de los datos sin recuperar grandes conjuntos de resultados.

• Entre bases de datos: pasa database.table para muestrear bases de datos distintas de MYSQL_DATABASE; los nombres de tabla simples usan la base de datos configurada.

• Reglas de identificadores: los nombres solo pueden contener caracteres alfanuméricos, guiones bajos y $ (se permite un punto como separador de database.table).

Prompts disponibles

Además de las herramientas, el servidor ofrece prompts MCP: flujos de trabajo guiados de varios pasos que el cliente puede iniciar bajo demanda. Aparecen como comandos de barra en Claude Code (/mcp__<server>__<prompt>) y en el menú de avisos (+) de Claude Desktop.

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 la lista de recursos para enumerar tablas.

Uso

Con Claude Desktop

Añade lo siguiente a 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"
      }
    }
  }
}

Consulta MCP_USECASES.md para ver ejemplos más detallados e instrucciones específicas para cada agente.

Con Visual Studio Code

Añade lo siguiente a 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: es necesario tener uv instalado.

Depuración con MCP Inspector

MySQL MCP Server no está diseñado para ejecutarse de forma independiente ni iniciarse directamente desde la línea de comandos de Python, pero puedes depurarlo con MCP Inspector.

MCP Inspector ofrece una forma cómoda de probar y depurar implementaciones de MCP:

# 安装依赖
pip install -r requirements.txt
# 使用 MCP Inspector 调试（不要直接用 Python 运行）

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

Desarrollo

# 克隆仓库
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 上用 `venv\Scripts\activate`
# 安装开发依赖
pip install -r requirements-dev.txt
# 复制示例配置并填入你的凭据
cp .env.example .env
# 编辑 .env，填入 MySQL 连接信息
# 运行测试
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 someten a una estricta validación de lista blanca (solo se permiten caracteres alfanuméricos, guiones bajos y $; se permite un punto como separador de database.table). Cualquier otro carácter especial se rechaza para evitar la inyección de SQL.

• Acceso cifrado: soporte completo de SSL/TLS y túneles SSH para proteger las conexiones remotas.

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

• Mínimos privilegios: utiliza siempre un usuario MySQL dedicado con los permisos mínimos necesarios.

• El transporte SSE no tiene autenticación integrada. El servidor SSE se vincula a 0.0.0.0 de forma predeterminada y acepta conexiones sin credenciales. Si se expone más allá de localhost, colócalo detrás de un proxy inverso con autenticación obligatoria (nginx, Caddy, Traefik). Ejemplo de nginx + 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 escuche solo en la interfaz de bucle local, convirtiendo al proxy en la única entrada pública. Define MCP_SSE_ALLOWED_HOSTS con el nombre de host público reenviado por el proxy (por ejemplo, MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

Consulta la guía completa de implementación segura en SECURITY.md.

Buenas prácticas de seguridad

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

1. Crea un usuario MySQL dedicado con los mínimos privilegios

2. Nunca uses credenciales de root ni cuentas de administrador

3. Limita el acceso a la base de datos a las operaciones necesarias

4. Habilita el registro para auditoría

5. Revisa periódicamente la seguridad del acceso a la base de datos

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

• Crear usuarios MySQL restringidos

• Configurar permisos adecuados

• Supervisar el acceso a la base de datos

• Buenas 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 más detalles.

Contribuciones

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)

3. Haz commit de los cambios (git commit -m 'Add some amazing feature')

4. Sube la rama (git push origin feature/amazing-feature)

5. Abre un Pull Request