MySQL MCP Server

Un servidor MCP para acceder y gestionar bases de datos MySQL.

Documentación

Servidor MCP de MySQL

Un servidor de Model Context Protocol (MCP) que proporciona acceso a bases de datos MySQL a través de herramientas estandarizadas.

Características

Ejecución de consultas: Ejecuta consultas SQL arbitrarias
Inspección de esquemas: Visualiza esquemas de tablas
Listado de tablas: Lista todas las tablas de la base de datos
Análisis de consultas: Analiza planes de ejecución de consultas con sugerencias de optimización

Requisitos

Go 1.21+ (desarrollado con Go 1.23.6)
MySQL 5.7+ o MySQL 8.0+
Make (para comandos de compilación)

Instalación

Opción 1: Descargar binario precompilado (Recomendado)

Descarga la última versión para tu plataforma:

Linux (amd64):

curl -L https://github.com/koh/mysql-mcp-server/releases/latest/download/mysql-mcp-server-linux-amd64.tar.gz | tar xz
chmod +x mysql-mcp-server
sudo mv mysql-mcp-server /usr/local/bin/

macOS (Apple Silicon):

curl -L https://github.com/koh/mysql-mcp-server/releases/latest/download/mysql-mcp-server-darwin-arm64.tar.gz | tar xz
chmod +x mysql-mcp-server
mv mysql-mcp-server /usr/local/bin/

macOS (Intel):

curl -L https://github.com/koh/mysql-mcp-server/releases/latest/download/mysql-mcp-server-darwin-amd64.tar.gz | tar xz
chmod +x mysql-mcp-server
mv mysql-mcp-server /usr/local/bin/

Windows:

# Download from https://github.com/koh/mysql-mcp-server/releases/latest
# Extract mysql-mcp-server-windows-amd64.zip
# Add to PATH or move mysql-mcp-server.exe to a directory in PATH

Opción 2: Compilar desde el código fuente

Clona el repositorio:

git clone https://github.com/koh/mysql-mcp-server.git
cd mysql-mcp-server

Instala las dependencias y compila:

make build
# Or use make setup for full development setup

Verificar la instalación

Después de la instalación, verifica que el servidor sea accesible:

mysql-mcp-server --version

Configuración

El servidor utiliza variables de entorno para la configuración de conexión a MySQL:

MYSQL_HOST: Host del servidor MySQL (predeterminado: localhost)
MYSQL_PORT: Puerto del servidor MySQL (predeterminado: 3306)
MYSQL_USER: Nombre de usuario de MySQL
MYSQL_PASSWORD: Contraseña de MySQL
MYSQL_DATABASE: Nombre de la base de datos a la que conectarse

Puedes copiar .env.example a .env y modificarlo con tus credenciales:

cp .env.example .env

Uso

Con Claude Desktop

Agrega el servidor a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-server",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Uso directo

Ejecuta el servidor directamente:

export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=password
export MYSQL_DATABASE=testdb
./mysql-mcp-server

Herramientas disponibles

query

Ejecuta consultas SELECT para recuperar datos de la base de datos MySQL. Esta herramienta está restringida únicamente a sentencias SELECT por seguridad. Usa la herramienta execute para operaciones de modificación de datos.

Parámetros:

query (obligatorio): Solo sentencias SELECT
format (opcional): Formato de salida - json, table, csv o markdown (predeterminado: table)

Ejemplo:

{
  "name": "query",
  "arguments": {
    "query": "SELECT * FROM users WHERE status = 'active' LIMIT 10",
    "format": "csv"
  }
}

execute

Ejecuta consultas INSERT, UPDATE, DELETE con comprobaciones de seguridad. Esta herramienta implementa un proceso de ejecución en dos pasos por seguridad:

Primero ejecuta con dry_run=true para previsualizar las filas afectadas
Luego ejecuta con dry_run=false y el token de confirmación para ejecutar

Parámetros:

sql (obligatorio): Sentencia INSERT, UPDATE o DELETE
dry_run (opcional): Si es true, muestra las filas afectadas sin ejecutar (predeterminado: true)
confirm_token (opcional): Token de la respuesta de ejecución en seco, requerido cuando dry_run=false

Ejemplo - Paso 1 (Ejecución en seco):

{
  "name": "execute",
  "arguments": {
    "sql": "UPDATE users SET status = 'inactive' WHERE last_login < '2024-01-01'",
    "dry_run": true
  }
}

Respuesta:

{
  "content": [
    {"type": "text", "text": "DRY RUN - Operation: UPDATE"},
    {"type": "text", "text": "This operation will affect 42 rows"},
    {"type": "text", "text": "To execute this query, run again with dry_run=false and the confirmation token below:"},
    {"type": "text", "text": "confirm_token: abc123def456"}
  ],
  "affected_rows": 42,
  "operation": "UPDATE",
  "confirm_token": "abc123def456"
}

Ejemplo - Paso 2 (Ejecutar):

{
  "name": "execute",
  "arguments": {
    "sql": "UPDATE users SET status = 'inactive' WHERE last_login < '2024-01-01'",
    "dry_run": false,
    "confirm_token": "abc123def456"
  }
}

schema

Obtiene el esquema de una tabla de MySQL.

Parámetros:

table (obligatorio): El nombre de la tabla

Ejemplo:

{
  "name": "schema",
  "arguments": {
    "table": "users"
  }
}

tables

Lista todas las tablas de la base de datos.

Ejemplo:

{
  "name": "tables",
  "arguments": {}
}

explain

Analiza el plan de ejecución de una consulta MySQL para comprender el rendimiento. Admite tanto EXPLAIN como EXPLAIN ANALYZE.

Parámetros:

query (obligatorio): La consulta SQL a analizar
analyze (opcional): Si es true, ejecuta EXPLAIN ANALYZE para obtener estadísticas de ejecución reales (predeterminado: false)

Ejemplo - EXPLAIN básico:

{
  "name": "explain",
  "arguments": {
    "query": "SELECT * FROM users WHERE email = 'test@example.com'"
  }
}

Ejemplo - EXPLAIN ANALYZE:

{
  "name": "explain",
  "arguments": {
    "query": "SELECT * FROM users WHERE age > 25",
    "analyze": true
  }
}

Nota: EXPLAIN ANALYZE realmente ejecuta la consulta para recopilar estadísticas de ejecución reales, incluidos recuentos de filas reales e información de tiempo. Úsalo con precaución en consultas que modifiquen datos o que tarden mucho tiempo en ejecutarse.

Integración con herramientas de IA

Integración con VSCode

Opción 1: Usar extensiones de cliente MCP

Configura en settings.json de VSCode:

{
  "mcp.servers": {
    "mysql": {
      "command": "/path/to/mysql-mcp-server",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "password",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

Opción 2: Extensión personalizada de VSCode

Crea una extensión personalizada que inicie el servidor MCP. Consulta INTEGRATION.md para detalles de implementación.

Integración con Cursor

Cursor admite servidores MCP a través de su configuración:

Abre la Configuración de Cursor
Navega a "AI" → "Model Context Protocol"
Agrega la configuración del servidor:

{
  "mysql": {
    "command": "/path/to/mysql-mcp-server",
    "env": {
      "MYSQL_HOST": "localhost",
      "MYSQL_USER": "root",
      "MYSQL_PASSWORD": "password",
      "MYSQL_DATABASE": "mydb"
    }
  }
}

Integración con GitHub Copilot

GitHub Copilot no admite directamente servidores MCP, pero puedes crear un puente a través de extensiones de VSCode. Consulta INTEGRATION.md para la implementación detallada.

Patrón de integración genérico

Para cualquier herramienta que admita comunicación por subprocesos:

const { spawn } = require('child_process');

class MCPClient {
    constructor(serverPath, env) {
        this.server = spawn(serverPath, [], { env });
        // ... handle communication
    }

    async callTool(name, arguments) {
        return this.request('tools/call', { name, arguments });
    }
}

// Usage
const client = new MCPClient('/path/to/mysql-mcp-server', {
    MYSQL_HOST: 'localhost',
    MYSQL_USER: 'root',
    MYSQL_PASSWORD: 'password',
    MYSQL_DATABASE: 'mydb'
});

Para ejemplos completos de integración y solución de problemas, consulta INTEGRATION.md.

Pruebas

Para instrucciones detalladas de prueba, consulta TESTING.md.

Inicio rápido:

# Setup and run interactive test client
make setup
make test-client

Desarrollo

Ejecuta las pruebas:

make test

Ejecuta el servidor:

make run

Consideraciones de seguridad

La herramienta query está restringida únicamente a sentencias SELECT para evitar la modificación accidental de datos
La herramienta execute requiere un proceso de confirmación en dos pasos para todas las operaciones de modificación de datos
Nunca expongas este servidor a clientes no confiables
Usa permisos de usuario de MySQL apropiados
Considera usar usuarios de base de datos de solo lectura cuando sea posible
La función de ejecución en seco te permite previsualizar el impacto de las operaciones UPDATE/DELETE antes de ejecutarlas
Los tokens de confirmación expiran después de 5 minutos por seguridad
Mantén seguras tus credenciales de base de datos

Licencia

MIT