sqlite-readonly-mcp

Un servicio de SQLite de solo lectura para Model Context Protocol que se ejecuta en Linux remoto, utilizando Streamable HTTP (/mcp), autenticado mediante Bearer Token, y devolviendo los resultados de las consultas como texto JSON. Diseñado para colocarse detrás de Nginx (HTTPS), con el upstream escuchando únicamente en la máquina local.

Funcionalidades

• Herramienta sqlite_query: SELECT / WITH / EXPLAIN individual, devuelve JSON con { rows, rowCount }.

• Herramienta list_tables: Lista los nombres de tablas que no son del sistema.

• SQLite: better-sqlite3 readonly + fileMustExist; limitación a nivel de aplicación de una sola sentencia y prefijo de consulta.

• GET /health: Solo para acceso de bucle local (loopback), utilizado para sondas (ver src/server.ts).

• Transporte: Streamable HTTP (/mcp) + SSE heredado (GET /sse, POST /messages), para facilitar el respaldo (fallback) de Cursor cuando sea necesario.

Related MCP server: PostgreSQL MCP Server

Variables de entorno

Construcción y ejecución local

npm install
npm run build
export SQLITE_PATH=/path/to/db.sqlite
export BEARER_TOKEN='your-secret-token'
export ALLOWED_HOSTS='127.0.0.1,localhost'
node dist/server.js

Desarrollo y depuración: npm run dev

Nginx y systemd

Consulte deploy/nginx.example.conf, deploy/sqlite-readonly-mcp.service, deploy/sqlite-readonly-mcp.env.example.

Puntos clave: pasar Authorization, Accept, Content-Type, mcp-session-id al upstream; desactivar proxy_buffering para respuestas SSE/fragmentadas. El ejemplo ya incluye **/sse**, **/messages** (respaldo SSE heredado), junto con el /mcp de Streamable HTTP para el proxy inverso.

Ejecución como usuario root (ejemplo recomendado)

Para simplificar la configuración de permisos de lectura del archivo SQLite y su directorio padre, el ejemplo utiliza root para iniciar el servicio (en la unidad de systemd no se establece User= / Group=, por lo que el valor predeterminado es root).

1. Coloque el código y los artefactos de construcción en, por ejemplo, /opt/sqlite-readonly-mcp, y ejecute npm ci --omit=dev y npm run build.

2. Copie el archivo de entorno y rellene las variables:

 sudo cp deploy/sqlite-readonly-mcp.env.example /etc/sqlite-readonly-mcp.env
 sudo chmod 600 /etc/sqlite-readonly-mcp.env

3. Instale y habilite la unidad (modifique WorkingDirectory y la ruta absoluta de node en ExecStart según sea necesario):

 sudo cp deploy/sqlite-readonly-mcp.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable --now sqlite-readonly-mcp
 sudo systemctl status sqlite-readonly-mcp

Si anteriormente añadió User=mcp por su cuenta, elimine esa línea antes de ejecutar daemon-reload y restart.

Nota de seguridad: El impacto de una brecha en un proceso root es mayor, por lo que es imperativo utilizar HTTPS, Bearer, escucha local + Nginx, y firewall; si se requiere el mínimo privilegio, puede volver a un usuario dedicado y configurar los permisos del archivo de datos y la ruta por separado.

Verificación manual (curl)

MCP requiere que el cliente acepte tanto application/json como text/event-stream:

curl -sS -D - \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
  "https://mcp.example.com/mcp"

Un token incorrecto debería devolver 401.

Cliente Cursor

En la configuración de MCP de Cursor, configure la URL HTTPS para este servicio remoto (por ejemplo, https://mcp.example.com/mcp). Si necesita Bearer, verifique si su versión actual de Cursor admite la configuración de cabeceras personalizadas para MCP remoto; si no es así, deberá añadir una capa de puerta de enlace local con Authorization fijo (ver advertencias de riesgo de la solución).

Operaciones

Detalles en docs/RUNBOOK.md.

Licencia

MIT (coherente con @modelcontextprotocol/sdk; sujeto a las licencias de cada dependencia).