sqlite-readonly-mcp

Ein auf einem Remote-Linux laufender schreibgeschützter SQLite Model Context Protocol-Dienst, der Streamable HTTP (/mcp) verwendet, durch Bearer Token authentifiziert wird und Abfrageergebnisse als JSON-Text zurückgibt. Konzipiert für den Betrieb hinter Nginx (HTTPS), wobei der Upstream nur auf dem lokalen Host lauscht.

Funktionen

• Tool sqlite_query: Einzelne SELECT / WITH / EXPLAIN-Abfragen, gibt JSON mit { rows, rowCount } zurück.

• Tool list_tables: Listet Nicht-System-Tabellennamen auf.

• SQLite: better-sqlite3 readonly + fileMustExist; Anwendungsebene beschränkt auf einzelne Anweisungen und Abfragepräfixe.

• GET /health: Nur für Loopback-Zugriffe, für Probes (siehe src/server.ts).

• Transport: Streamable HTTP (/mcp) + Legacy SSE (GET /sse, POST /messages), um Cursor bei Bedarf ein Fallback zu ermöglichen.

Related MCP server: PostgreSQL MCP Server

Umgebungsvariablen

Lokales Bauen und Ausführen

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

Entwicklung und Debugging: npm run dev

Nginx und systemd

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

Wichtige Punkte: Übermittlung von Authorization, Accept, Content-Type, mcp-session-id an den Upstream; proxy_buffering für SSE/Chunked-Antworten deaktivieren. Das Beispiel enthält bereits **/sse**, **/messages** (Legacy SSE-Fallback), die zusammen mit Streamable HTTP /mcp als Reverse Proxy fungieren.

Ausführung als Root-Benutzer (empfohlenes Beispiel)

Zur Vereinfachung der Konfiguration der Leseberechtigungen für die SQLite-Datei und das übergeordnete Verzeichnis startet das Beispiel den Dienst als root (in der systemd-Unit ist kein User= / Group= gesetzt, standardmäßig ist dies root).

1. Platzieren Sie den Code und die Build-Artefakte z. B. unter /opt/sqlite-readonly-mcp und führen Sie npm ci --omit=dev sowie npm run build aus.

2. Kopieren Sie die Umgebungsdatei und füllen Sie die Variablen aus:

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

3. Installieren und aktivieren Sie die Unit (passen Sie WorkingDirectory und den absoluten Pfad zu node in ExecStart bei Bedarf an):

 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

Falls Sie zuvor manuell User=mcp hinzugefügt haben, löschen Sie diese Zeile, bevor Sie daemon-reload und restart ausführen.

Sicherheitshinweis: Ein kompromittierter Root-Prozess hat größere Auswirkungen. Bitte verwenden Sie unbedingt HTTPS, Bearer, lokales Lauschen + Nginx, Firewall; falls minimale Berechtigungen erforderlich sind, können Sie zu einem dedizierten Benutzer zurückkehren und die Berechtigungen für Datendateien und Pfade separat konfigurieren.

Manuelle Überprüfung (curl)

MCP erfordert, dass der Client sowohl application/json als auch text/event-stream akzeptiert:

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"

Ein falsches Token sollte 401 zurückgeben.

Cursor-Client

Konfigurieren Sie in den MCP-Einstellungen von Cursor die HTTPS-URL für diesen Remote-Dienst (z. B. https://mcp.example.com/mcp). Falls Bearer erforderlich ist, prüfen Sie, ob die aktuelle Cursor-Version das Konfigurieren von benutzerdefinierten Headern für Remote-MCPs unterstützt; falls nicht, muss lokal eine zusätzliche Gateway-Schicht mit festem Authorization-Header hinzugefügt werden (siehe Risikohinweise).

Betrieb

Siehe docs/RUNBOOK.md für Details.

Lizenz

MIT (identisch mit @modelcontextprotocol/sdk; es gelten die Lizenzen der jeweiligen Abhängigkeiten).