mysql-mcp-server

Un servidor de Model Context Protocol (MCP) que permite a un cliente MCP (Claude Desktop, Claude Code, etc.) ejecutar SQL contra una base de datos MySQL a través de cuatro herramientas: select, insert, update y delete.

El servidor se ejecuta como un paquete de Python gestionado por uv y se comunica con el cliente a través de stdio, como un subproceso iniciado por el cliente.

Requisitos

• Python 3.11+

• uv

• Un servidor MySQL accesible

Related MCP server: Universal Database MCP Server

Instalación

uv sync

Configuración

El servidor requiere seis valores, cada uno configurable mediante variable de entorno y/o flag de CLI (los flags de CLI tienen prioridad sobre las variables de entorno):

Si falta un valor obligatorio, o MYSQL_MODE no es readonly/readwrite, el servidor imprime un error en stderr y sale con el código de estado 1 sin iniciarse.

• Modo readonly: solo se permite la herramienta select. insert/update/delete se rechazan con un error PERMISSION_DENIED.

• Modo readwrite: se permiten las cuatro herramientas.

El modo es fijo durante toda la vida del proceso; no se puede cambiar en tiempo de ejecución.

Recomendación de seguridad: el modo readonly es una salvaguarda a nivel de aplicación, no un sustituto de los privilegios de la base de datos. Cuando sea posible, apunta el modo readonly a una cuenta de MySQL que solo tenga permisos SELECT.

¿Se necesita un archivo .env? No. El servidor nunca lee archivos .env — solo lee flags de CLI y variables de entorno reales del proceso (os.environ). Cómo consigues que los valores lleguen a ese entorno depende de cómo lo ejecutes:

• Como servidor MCP (consulta Conectarse desde un cliente MCP más abajo): el cliente (Claude Desktop/Code) lanza el proceso del servidor e inyecta el bloque env de su propia configuración JSON directamente como variables de entorno. No interviene ni se necesita ningún archivo .env.

• Ejecutar la CLI directamente para desarrollo/pruebas locales: .env es solo una comodidad para no tener que export seis variables a mano. Copia .env.example a .env, rellena con valores reales y cárgalo explícitamente — no se lee automáticamente:

  uv run --env-file .env mysql-mcp-server

.env está ignorado por git y nunca debe incluirse en un commit.

Ejecución

# Environment variables (or use `uv run --env-file .env mysql-mcp-server`, see above)
export MYSQL_MODE=readonly
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=app_user
export MYSQL_PASSWORD=secret
export MYSQL_DATABASE=mydb
uv run mysql-mcp-server

# Or, equivalently, via CLI flags
uv run mysql-mcp-server \
  --mysql-mode readonly \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-user app_user \
  --mysql-password secret \
  --mysql-database mydb

Conectarse desde un cliente MCP

Claude Desktop / Claude Code

Añade una entrada a la configuración de servidor de tu cliente MCP (por ejemplo, claude_desktop_config.json de Claude Desktop, o .mcp.json para Claude Code):

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "mysql-mcp-server"
      ],
      "env": {
        "MYSQL_MODE": "readonly",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "app_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

Reinicia el cliente después de editar la configuración. Las herramientas select, insert, update y delete (sujetas a MYSQL_MODE) deberían estar entonces disponibles para el modelo.

Herramientas

Las cuatro herramientas aceptan {"query": string, "params"?: array} y usan siempre marcadores de posición de enlace de parámetros %s en query — nunca apliques formato de cadena a la entrada del usuario en una consulta.

Cada llamada a una herramienta devuelve una de las siguientes opciones:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

Códigos de error: PERMISSION_DENIED, INVALID_QUERY_TYPE, MULTI_STATEMENT_NOT_ALLOWED, DB_CONNECTION_ERROR, DB_EXECUTION_ERROR, INTERNAL_ERROR.

Las consultas de múltiples sentencias (separadas por ;) y cualquier sentencia DDL o de privilegios (DROP, TRUNCATE, ALTER, GRANT, CREATE USER, ...) se rechazan siempre, ya que solo se aceptan los cuatro tipos de sentencia permitidos mencionados anteriormente.

Desarrollo

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v
uv run uv build   # packaging check

Solución de problemas

• El servidor sale inmediatamente con el código de estado 1: falta un valor obligatorio MYSQL_* o MYSQL_MODE no es válido — consulta stderr para saber cuál.

• DB_CONNECTION_ERROR: MySQL no es accesible, o las credenciales son incorrectas. El servidor sigue ejecutándose y reintentará la conexión en la siguiente llamada a una herramienta.

• PERMISSION_DENIED en insert/update/delete: el servidor se está ejecutando en modo readonly; reinícialo con MYSQL_MODE=readwrite si se pretende escribir.

Historial de versiones

• 0.1.0 — Versión inicial: herramientas select/insert/update/delete, política de modos readonly/readwrite, transporte MCP por stdio, reconexión y reintento automáticos en conexiones perdidas.