libSQL by xexr

Servidor MCP para bases de datos libSQL con herramientas integrales de seguridad y gestión. Soporta bases de datos de archivo, HTTP local y Turso remoto con agrupación de conexiones, soporte de transacciones y 6 herramientas especializadas de base de datos.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP libSQL by xexr

Un servidor de Model Context Protocol (MCP) para operaciones de bases de datos libSQL, que proporciona acceso seguro a bases de datos a través de Claude Desktop, Claude Code, Cursor y otros clientes compatibles con MCP.

Se ejecuta en Node, escrito en TypeScript

🔧 Inicio rápido

Instalación:
```
pnpm install -g @xexr/mcp-libsql
```

Prueba local:

mcp-libsql --url file:///tmp/test.db --log-mode console

Configura Claude Desktop con la ruta de tu Node.js y la URL de la base de datos (consulta los ejemplos de configuración a continuación)

🚀 Estado

✅ Capacidades completas de gestión de bases de datos - Las 6 herramientas principales implementadas y probadas
✅ Validación de seguridad integral - 67 pruebas de seguridad que cubren todos los vectores de inyección
✅ Amplia cobertura de pruebas - 244 pruebas en total (177 unitarias + 67 de seguridad) con una tasa de aprobación del 100%
✅ Despliegue en producción verificado - Funciona correctamente con clientes MCP
✅ Manejo robusto de errores - Reintento de conexión, degradación gradual y registro de auditoría

🛠️ Características

Herramientas disponibles

read-query: Ejecuta consultas SELECT con validación de seguridad integral
write-query: Operaciones INSERT/UPDATE/DELETE con soporte de transacciones
create-table: Operaciones DDL para la creación de tablas con medidas de seguridad
alter-table: Modificaciones de la estructura de tablas (operaciones ADD/RENAME/DROP)
list-tables: Exploración de metadatos de la base de datos con opciones de filtrado
describe-table: Inspección del esquema de tablas con múltiples formatos de salida

Seguridad y fiabilidad

Prevención de inyección SQL multicapa con validación de seguridad integral
Agrupación de conexiones con monitoreo de salud y lógica de reintento automático
Soporte de transacciones con reversión automática en caso de errores
Registro de auditoría integral para el cumplimiento de seguridad

🔐 Detalles de seguridad: Consulta docs/SECURITY.md para conocer las funciones de seguridad integrales y las pruebas.

Experiencia de desarrollo

Formato de tablas elegante con alineación adecuada y manejo de NULL
Métricas de rendimiento mostradas para todas las operaciones
Mensajes de error claros con contexto accionable
Soporte de consultas parametrizadas para un manejo seguro de datos
Modo de desarrollo con registro mejorado y recarga en caliente

📋 Requisitos previos

Node.js 20+
pnpm (o npm) gestor de paquetes
Base de datos libSQL (basada en archivos o remota)
Claude Desktop (para la integración con MCP)

Requisitos de plataforma

macOS: Instalación nativa de Node.js
Linux: Instalación nativa de Node.js
Windows: Instalación nativa de Node.js o WSL2 con instalación de Node.js

🔧 Instalación

# Use your package manager of choice, e.g. npm, pnpm, bun etc

# Install globally
pnpm install -g @xexr/mcp-libsql
mcp-libsql -v # check version

# ...or build from the repository
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install # Install dependencies
pnpm build # Build the project
node dist/index.js -v  # check version

🚀 Uso

Pruebas locales

Se asume una instalación global a continuación; reemplaza "mcp-libsql" por "node dist/index.js" si usas una compilación local

# Test with file database (default: file-only logging)
mcp-libsql --url file:///tmp/test.db

# Test with HTTP database
mcp-libsql --url http://127.0.0.1:8080

# Test with Turso database (environment variable, alternatively export the env var)
LIBSQL_AUTH_TOKEN="your-token" mcp-libsql --url "libsql://your-db.turso.io"

# Test with Turso database (CLI parameter)
mcp-libsql --url "libsql://your-db.turso.io" --auth-token "your-token"

# Development mode with console logging
mcp-libsql --dev --log-mode console --url file:///tmp/test.db

# Test with different logging modes
mcp-libsql --url --log-mode both file:///tmp/test.db

Integración con Claude Desktop

Configura el servidor MCP en Claude Desktop según tu sistema operativo:

Configuración en macOS

Crea el archivo de configuración en ~/Library/Application Support/Claude/claude_desktop_config.json:

Instalación global


{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///Users/username/database.db"
      ]
    }
  }
}

Configuración alternativa para instalación con compilación local:

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/Users/username/projects/mcp-libsql/dist/index.js",
        "--url", 
        "file:///Users/username/database.db"
      ],
    }
  }
}

Configuración alternativa para instalación global usando nvm lts para node

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "zsh",
      "args": [
        "-c",
        "source ~/.nvm/nvm.sh && nvm use --lts > /dev/null && mcp-libsql --url file:///Users/username/database.db",
      ],
    }
  }
}

Importante: Se recomienda el método de instalación global, ya que maneja el PATH automáticamente.

Configuración en Linux

Crea el archivo de configuración en ~/.config/Claude/claude_desktop_config.json:

Instalación global

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///home/username/database.db"
      ]
    }
  }
}

Configuración alternativa para instalación con compilación local:

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/home/username/projects/mcp-libsql/dist/index.js",
        "--url",
        "file:///home/username/database.db"
      ],
    }
  }
}

Configuración en Windows (WSL2)

Crea el archivo de configuración en %APPDATA%\Claude\claude_desktop_config.json:

Instalación global

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

Configuración alternativa para instalación con compilación local:

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "/home/username/projects/mcp-libsql/dist/index.js --url file:///home/username/database.db",
      ]
    }
  }
}

Configuración alternativa para instalación global usando nvm para node

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "source ~/.nvm/nvm.sh && mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

Importante: Usa wsl.exe -e (no solo wsl.exe) para garantizar un manejo adecuado de comandos y evitar problemas con la recepción de comandos del servidor en Windows.

Autenticación de base de datos

Para bases de datos Turso (y otras con credenciales), necesitarás un token de autenticación. Hay dos formas seguras de proporcionarlo:

Se muestra la instalación global a continuación; ajústala según tu configuración

Método 1: Variable de entorno (recomendado)

Configura Claude Desktop con variable de entorno (ejemplo para macOS/Linux):

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io"
      ]
    }
  }
}

Método 2: Parámetro de CLI

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io",
        "--auth-token",
        "your-turso-auth-token-here"
      ]
    }
  }
}

Cómo obtener tu token de autenticación de Turso

Instala la CLI de Turso:

curl -sSfL https://get.tur.so/install.sh | bash

Inicia sesión en Turso:
```
turso auth login
```

Crea un token de autenticación:

turso auth token create --name "mcp-libsql"

Obtén la URL de tu base de datos:
```
turso db show your-database-name --url
```

Mejores prácticas de seguridad

Las variables de entorno son más seguras que los parámetros de CLI (los tokens no aparecerán en las listas de procesos)
Los archivos de configuración de MCP pueden contener tokens - asegúrate de que no se confirmen en el control de versiones
Considera usar gestión externa de secretos para entornos de producción
Usa tokens con ámbito y permisos mínimos requeridos
Rota los tokens regularmente para mayor seguridad
Monitorea el uso de tokens a través del panel de Turso

Ejemplo: Configuración completa de Turso

Crea y configura la base de datos:

# Create database
turso db create my-app-db

# Get database URL
turso db show my-app-db --url
# Output: libsql://my-app-db-username.turso.io

# Create auth token
turso auth token create --name "mcp-libsql-token"
# Output: your-long-auth-token-string

Configura Claude Desktop:

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://my-app-db-username.turso.io"
      ]
    }
  }
}

Prueba la conexión:

# Test locally first
mcp-libsql --url "libsql://my-app-db-username.turso.io" --log-mode console

Notas de configuración

Rutas de archivos: Usa rutas absolutas para evitar problemas de resolución de rutas
URLs de base de datos:
- Bases de datos de archivos: file:///absolute/path/to/database.db
- Bases de datos HTTP: http://hostname:port
- libSQL/Turso: libsql://your-database.turso.io
Ruta de Node.js: Usa which node para encontrar la ruta de instalación de tu Node.js
Directorio de trabajo: Establece cwd para garantizar que las rutas relativas funcionen correctamente
Autenticación: Para bases de datos Turso, usa variables de entorno para un manejo seguro de tokens
Modos de registro:
- El modo file predeterminado evita errores de análisis JSON en el protocolo MCP
- Usa --log-mode console para depuración de desarrollo
- Usa --log-mode both para un registro integral
- Usa --log-mode none para deshabilitar todo el registro

Reinicia Claude Desktop por completo después de actualizar la configuración
Prueba la integración pidiéndole a Claude que ejecute consultas SQL:
```
Can you run this SQL query: SELECT 1 as test
```

📋 Herramientas disponibles

read-query - Ejecuta consultas SELECT con validación de seguridad
write-query - INSERT/UPDATE/DELETE con soporte de transacciones
create-table - CREATE TABLE con seguridad DDL
alter-table - Modifica la estructura de tablas (ADD/RENAME/DROP)
list-tables - Explora metadatos y objetos de la base de datos
describe-table - Inspecciona el esquema y la estructura de tablas

📖 Documentación detallada de la API: Consulta docs/API.md para ver ejemplos completos de entrada/salida y parámetros.

🧪 Pruebas

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test security-verification

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm typecheck

Cobertura de pruebas: 403 pruebas que cubren toda la funcionalidad, incluidos casos límite, escenarios de error, argumentos de CLI, autenticación y validación de seguridad integral.

⚠️ Problemas comunes

1. Errores de compilación

# Clean and rebuild
rm -rf dist node_modules
pnpm install && pnpm build

2. Problemas de versión de Node.js (macOS)

SyntaxError: Unexpected token '??='

Problema: Claude Desktop puede usar por defecto una versión anterior de Node.js en tu sistema que no admite el conjunto de funciones requerido.

Solución: Usa la instalación global y el método de selección de node con nvm que se muestra arriba.

3. El servidor no se inicia

Para instalación global: pnpm install -g @xexr/mcp-libsql
Para instalación local: Asegúrate de que se ejecutó pnpm build y que existe dist/index.js
Prueba local: mcp-libsql --url file:///tmp/test.db
Reinicia Claude Desktop después de los cambios de configuración

4. Herramientas no disponibles

Verifica que la URL de la base de datos sea accesible
Revisa los registros de Claude Desktop para ver errores de conexión
Prueba con una base de datos de archivos simple: file:///tmp/test.db

5. Errores de análisis JSON (resueltos)

Expected ',' or ']' after array element in JSON

Resuelto: Este problema es causado por el registro de consola en stdout. La opción --log-mode ahora usa por defecto el modo file, que evita este problema. Si ves estos errores, asegúrate de usar el --log-mode file predeterminado o de no especificar --log-mode en absoluto. Ten en cuenta que el error es inofensivo y la herramienta seguirá funcionando con él si deseas tener registro de consola.

6. Problemas de conexión a la base de datos

# Test database connectivity
sqlite3 /tmp/test.db "SELECT 1"

# Fix permissions
chmod 644 /path/to/database.db

🔧 Guía completa de solución de problemas: Consulta docs/TROUBLESHOOTING.md para ver soluciones detalladas a todos los problemas.

🏗️ Arquitectura

Construido con TypeScript y patrones modernos de Node.js:

Agrupación de conexiones con monitoreo de salud y lógica de reintento
Arquitectura basada en herramientas con validación y manejo de errores consistentes
Diseño centrado en la seguridad con validación de entrada multicapa
Pruebas integrales con 244 pruebas que cubren todos los escenarios

🤝 Contribuciones

Sigue el modo estricto de TypeScript y los patrones de código existentes
Escribe pruebas para las nuevas funciones
Mantén las medidas de seguridad
Actualiza la documentación

Desarrollo: pnpm dev • Compilación: pnpm build • Pruebas: pnpm test

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para obtener más detalles.

libSQL by xexr

Documentación

MCP libSQL by xexr

🔧 Inicio rápido

🚀 Estado

🛠️ Características

Herramientas disponibles

Seguridad y fiabilidad

Experiencia de desarrollo

📋 Requisitos previos

Requisitos de plataforma

🔧 Instalación

🚀 Uso

Pruebas locales

Integración con Claude Desktop

Configuración en macOS

Configuración en Linux

Configuración en Windows (WSL2)

Autenticación de base de datos

Método 1: Variable de entorno (recomendado)

Método 2: Parámetro de CLI

Cómo obtener tu token de autenticación de Turso

Mejores prácticas de seguridad

Ejemplo: Configuración completa de Turso

Notas de configuración

📋 Herramientas disponibles

🧪 Pruebas

⚠️ Problemas comunes

1. Errores de compilación

2. Problemas de versión de Node.js (macOS)

3. El servidor no se inicia

4. Herramientas no disponibles

5. Errores de análisis JSON (resueltos)

6. Problemas de conexión a la base de datos

🏗️ Arquitectura

🤝 Contribuciones

📄 Licencia

🔗 Enlaces