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.