MCP SQL Server (Desarrollo)

Servidor MCP profesional para conectar cualquier LLM compatible con MCP a una base de datos SQL y ejecutar:

• Consultas (SELECT, WITH, SHOW, etc.)

• DML (INSERT, UPDATE, DELETE)

• DDL (CREATE, ALTER, y opcionalmente DROP/TRUNCATE)

Este servidor está diseñado para uso personal en desarrollo asistido.

Características

• Protocolo MCP vía stdio (compatible con clientes MCP).

• Conexión multi-motor mediante SQLAlchemy (sqlite, postgresql, mysql, mssql, etc.).

• Herramientas MCP enfocadas en operación diaria:

  • sql_capabilities

  • sql_list_tables

  • sql_describe_table

  • sql_run

  • sql_run_script

• Bloqueo de DDL destructivo por defecto (DROP/TRUNCATE bloqueados).

• Límite configurable de filas y de sentencias por script.

Instalación

python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuración (variables de entorno)

Prefijo: MCP_SQL_

• MCP_SQL_DATABASE_URL: URL SQLAlchemy. Default: sqlite:///./dev.db

• MCP_SQL_MAX_ROWS: máximo de filas devueltas por consulta. Default: 200

• MCP_SQL_MAX_SCRIPT_STATEMENTS: máximo de sentencias por script. Default: 100

• MCP_SQL_ALLOW_DESTRUCTIVE_DDL: true/false para permitir DROP y TRUNCATE. Default: false

Ejemplo

export MCP_SQL_DATABASE_URL='postgresql+psycopg://dev_user:dev_pass@localhost:5432/devdb'
export MCP_SQL_MAX_ROWS=500
export MCP_SQL_ALLOW_DESTRUCTIVE_DDL=false

Ejecutar el servidor

mcp-sql-server

También puedes ejecutarlo como módulo:

python -m mcp_sql_server.server

Inicio con doble click en Windows

Se incluye el archivo start_mcp_sql_server.bat para facilitar el arranque:

1. Crea .venv automáticamente (si no existe).

2. Instala/actualiza dependencias.

3. Levanta el servidor MCP.

Solo haz doble click en ese .bat.

Configuración en un cliente MCP (ejemplo genérico)

{
  "mcpServers": {
    "sql-dev": {
      "command": "mcp-sql-server",
      "env": {
        "MCP_SQL_DATABASE_URL": "sqlite:///./dev.db",
        "MCP_SQL_MAX_ROWS": "200",
        "MCP_SQL_ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

Flujo recomendado

1. sql_capabilities para verificar configuración activa.

2. sql_list_tables para explorar el esquema.

3. sql_describe_table para inspeccionar metadatos.

4. sql_run para consultas o DML puntual.

5. sql_run_script para lotes de cambios controlados.

Buenas prácticas para desarrollo asistido

• Usa usuarios de base de datos con privilegios mínimos.

• Trabaja sobre una DB local de desarrollo o snapshot desechable.

• Mantén MCP_SQL_ALLOW_DESTRUCTIVE_DDL=false por defecto.

• Versiona cambios estructurales con migraciones.

Nota de seguridad

Este proyecto no está endurecido para producción. Está orientado a productividad local en entornos de desarrollo.

Guía Claude en VS Code

Revisa README_CLAUDE_VSCODE.md para un ejemplo completo de configuración y uso.