Servidor MCP de SQLPad

Un servidor MCP para SQLPad. Apunta un agente de IA a una instancia de SQLPad con su URL base y un token de servicio, y el agente puede descubrir conexiones, inspeccionar esquemas, ejecutar SQL y gestionar consultas guardadas.

Requisitos

• Node.js 20 o posterior.

• Una instancia de SQLPad accesible.

• El servidor de SQLPad debe tener SQLPAD_SERVICE_TOKEN_SECRET configurado. Sin él, cada solicitud autenticada con Bearer devuelve 401 Unauthorized.

• Un token de servicio generado en la interfaz de administración de SQLPad.

Related MCP server: SQLite Database MCP Server

Inicio rápido

No se necesita paso de instalación: ejecútalo directamente desde npm:

SQLPAD_SERVICE_TOKEN=... npx sqlpad-mcp --base-url https://sqlpad.example.com

O instálalo globalmente:

npm install -g sqlpad-mcp

El servidor habla MCP sobre stdio, por lo que normalmente lo lanza un cliente MCP en lugar de ejecutarse manualmente. Ejecutarlo directamente sigue siendo útil para verificar las credenciales: en caso de éxito, registra la versión detectada de SQLPad en stderr.

Configuración

Un indicador CLI tiene prioridad sobre la variable de entorno correspondiente. El intervalo de sondeo de lotes (250 ms) es interno y no configurable.

Configuración de Claude Code

Añade el servidor a tu mcp.json de Claude Code:

{
  "mcpServers": {
    "sqlpad": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "sqlpad-mcp",
        "--base-url",
        "https://sqlpad.example.com"
      ],
      "env": {
        "SQLPAD_SERVICE_TOKEN": "..."
      }
    }
  }
}

Proporcionar el token a través de env lo mantiene fuera de la lista de argumentos del proceso, que es legible por cualquier usuario mediante ps.

Para habilitar los grupos de herramientas restringidas, añade "SQLPAD_ALLOW_WRITES": "true" o "SQLPAD_ALLOW_ADMIN": "true" al mismo bloque env.

Herramientas

Doce herramientas están siempre registradas. Seis más están restringidas detrás de los dos indicadores SQLPAD_ALLOW_* y están desactivadas por defecto.

Ejecución

Descubrimiento

Consultas guardadas

Escritura de consultas guardadas: requiere SQLPAD_ALLOW_WRITES=true

Administración: requiere SQLPAD_ALLOW_ADMIN=true

Estas llaman a endpoints de SQLPad que a su vez requieren un token de servicio de administrador.

Cómo funciona la ejecución de SQL

SQLPad ejecuta SQL mediante lotes asíncronos. Crear un lote devuelve inmediatamente; cada sentencia pasa de queued a started, y luego a finished o error. Los resultados se obtienen por separado para cada sentencia y no están disponibles hasta que esa sentencia termina.

La herramienta run_sql absorbe todo el protocolo (crear, sondear, obtener y devolver filas), de modo que un agente hace una sola llamada. Si el sondeo alcanza el tiempo de espera configurado, la herramienta devuelve un batchId que el agente puede reanudar en lugar de quedarse colgado.

Las conexiones pueden no tener una base de datos predeterminada. Califica los nombres de tabla como schema.table y usa get_connection_schema para descubrir los esquemas disponibles.

Seguridad

• run_sql ejecuta SQL arbitrario, incluidos DDL y DML, y no está aislado. SQLPAD_ALLOW_WRITES solo restringe la mutación de los objetos de consultas guardadas de SQLPad; no restringe el contenido SQL. Usa credenciales de base de datos de solo lectura en la propia conexión de SQLPad. Esa es la única aplicación real.

• Los endpoints /api/service-tokens de SQLPad no se exponen deliberadamente. Una herramienta que acuña credenciales es una primitiva de escalada de privilegios.

• Las herramientas de administración están desactivadas por defecto.

• El token de servicio se redacta de todos los errores y registros. Todo el registro va a stderr porque stdout es el canal JSON-RPC.

• Los lotes están limitados al propio usuario del token, por lo que el servidor solo ve su propio historial de consultas.

Contribuciones

Clona el repositorio e instala las dependencias:

git clone https://github.com/VAIBHAV7500/sqlpad-mcp.git
cd sqlpad-mcp
npm install
npm run build

Crea una rama para tu cambio. Antes de abrir una solicitud de extracción, ejecuta:

npm run typecheck && npm run lint && npm test

CI ejecuta los mismos tres comandos en Node 20 y 22.

Licencia

MIT