@yuuzu/sql-mcp

npm version

Un servidor del Protocolo de Contexto de Modelo (MCP) para operaciones con bases de datos MSSQL, PostgreSQL y SQLite.

Instalación

# Using bunx (recommended)
bunx @yuuzu/sql-mcp

# Using npx
npx @yuuzu/sql-mcp

Características

Soporte para múltiples bases de datos: MSSQL, PostgreSQL y SQLite (vía better-sqlite3)
8 herramientas para operaciones de base de datos
Tres modos de consulta: safe, write, full
Autenticación avanzada: Windows Auth (MSSQL), certificados SSL (PostgreSQL)

Herramientas

Herramienta	Descripción
`connect-database`	Conectarse a un servidor de base de datos
`disconnect`	Desconectarse de la conexión actual
`connection-status`	Comprobar el estado de la conexión y el modo de consulta
`list-databases`	Listar todas las bases de datos en el servidor
`switch-database`	Cambiar a una base de datos diferente
`list-tables`	Listar todas las tablas y vistas
`describe-table`	Obtener detalles del esquema de la tabla
`execute-query`	Ejecutar consultas SQL

Modos de consulta

Controle los permisos de consulta mediante la variable de entorno SQL_MCP_MODE:

Modo	Operaciones permitidas	Descripción
`safe` (predeterminado)	SELECT, WITH, EXPLAIN	Solo lectura, el más seguro
`write`	+ INSERT, UPDATE, DELETE	Permite la modificación de datos
`full`	+ CREATE, DROP, ALTER, TRUNCATE	Acceso total, usar con precaución

Nota: Las sentencias PRAGMA (p. ej. PRAGMA table_info(users)) están permitidas en todos los modos, incluido safe, ya que son consultas de metadatos de solo lectura utilizadas habitualmente con SQLite.

# Example: Enable write mode
SQL_MCP_MODE=write bunx @yuuzu/sql-mcp

Ejemplos de uso

Configuración de Claude Desktop

Añadir a su claude_desktop_config.json:

{
    "mcpServers": {
        "sql-mcp": {
            "command": "bunx",
            "args": ["@yuuzu/sql-mcp"],
            "env": {
                "SQL_MCP_MODE": "safe"
            }
        }
    }
}

Conectarse a MSSQL

{
    "tool": "connect-database",
    "arguments": {
        "engine": "mssql",
        "server": "localhost",
        "port": 1433,
        "user": "sa",
        "password": "your_password",
        "database": "master"
    }
}

Conectarse a PostgreSQL

{
    "tool": "connect-database",
    "arguments": {
        "engine": "postgres",
        "server": "localhost",
        "port": 5432,
        "user": "postgres",
        "password": "your_password",
        "database": "postgres"
    }
}

Conectarse con autenticación de Windows (MSSQL)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "mssql",
        "server": "localhost",
        "windowsAuth": true
    }
}

Conectarse con SSL (PostgreSQL)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "postgres",
        "server": "your-server.com",
        "user": "postgres",
        "password": "your_password",
        "ssl": {
            "rejectUnauthorized": true,
            "ca": "/path/to/ca-certificate.crt"
        }
    }
}

Conectarse a SQLite (archivo)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": "/absolute/path/to/database.db"
    }
}

Conectarse a SQLite (en memoria)

Útil para pruebas, demostraciones o espacios de trabajo temporales.

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": ":memory:"
    }
}

Conectarse a SQLite (solo lectura)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": "/absolute/path/to/database.db",
        "readonly": true,
        "fileMustExist": true
    }
}

Nota de tiempo de ejecución de SQLite: El soporte de SQLite utiliza better-sqlite3, que requiere Node.js. Al ejecutar mediante bunx, MSSQL y PostgreSQL funcionan normalmente, pero las conexiones a SQLite devolverán un error claro indicándole que utilice npx o node en su lugar.

Desarrollo

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Build
bun run build

# Type check
bun run typecheck

Lanzamiento

Los lanzamientos están automatizados mediante GitHub Actions. Para crear un nuevo lanzamiento:

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

Esto hará lo siguiente:

Compilar el proyecto
Publicar en npm con procedencia
Crear un lanzamiento en GitHub con notas de lanzamiento generadas automáticamente

Requisitos: Establecer el secreto NPM_TOKEN en la configuración de su repositorio de GitHub.

Licencia

MIT

sql-mcp