db-mcp

Ein schreibgeschützter MCP-Server, der einem KI-Agenten sicheren Zugriff auf eine kleine SQLite-Shop-Datenbank (shop.db) bietet: Schema-Erkundung, frei formuliertes, schreibgeschütztes SQL und vorgefertigte Analyseberichte.

Installation

npm install

Related MCP server: SQLite Read-Only MCP Server

Konfiguration

Der Server liest SHOP_DB_PATH aus der Prozessumgebung, um die Datenbankdatei zu finden. Die Variable ist optional – ist sie nicht gesetzt, verwendet der Server shop.db im Projektverzeichnis. .env-Dateien werden nicht automatisch gelesen (es gibt weder eine dotenv-Abhängigkeit noch ein --env-file-Flag in den Skripten von package.json); .env.example ist nur als Erinnerung an den Variablennamen angegeben. Setzen Sie SHOP_DB_PATH in der tatsächlichen Umgebung, in der der Server läuft – bei einem stdio-MCP-Client entspricht das dem env-Schlüssel seiner Konfiguration (siehe „Client verbinden“ unten).

Build

npm run build

Ausführen

npm start
# or directly:
node dist/index.js

Der Server spricht MCP über stdio – er wird also als Kindprozess von einem MCP-Client/-Host gestartet und nicht interaktiv ausgeführt.

Client verbinden

Allgemeine stdio-MCP-Client-Konfiguration:

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/db-mcp/dist/index.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/shop.db" }
    }
  }
}

Claude Desktop: Fügen Sie denselben Block unter mcpServers in claude_desktop_config.json ein (die Position der Konfigurationsdatei je Betriebssystem finden Sie in MCP.md) und starten Sie Claude Desktop anschließend neu.

Tools

Sicherheitshinweise

• Die Datenbankverbindung wird mit { readonly: true, fileMustExist: true } geöffnet – die SQLite-Engine verweigert physisch jede Schreiboperation, unabhängig davon, welches SQL gesendet wird.

• Das query-Tool validiert zusätzlich, dass die Eingabe eine einzelne SELECT-Anweisung (oder WITH ... SELECT) ist, bevor sie überhaupt die Datenbank erreicht; INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/PRAGMA/ATTACH/DETACH/REPLACE/VACUUM/REINDEX/TRIGGER und Mehrfachanweisungen werden mit einer freundlichen Fehlermeldung abgelehnt.

• Fehler werden an der Grenze jedes Tools abgefangen und als MCP-Tool-Ergebnis mit isError: true und einer kurzen Meldung zurückgegeben – es werden niemals Stack-Traces oder Dateisystempfade an den Client gesendet.

• Alle Logs gehen auf stderr (console.error) – stdout ist ausschließlich für den JSON-RPC-Protokollstream reserviert.

Tests

npm test

Führt node --test (über tsx) für jede *.test.ts-Datei aus: Unit-Tests für die SQL-Prüfung, die Datenbankverbindung und die Abfragelogik jedes Tools gegen die echte shop.db, zusätzlich ein End-to-End-Test, der den kompilierten Server startet und ihn über stdio mit einem echten MCP-Client ansteuert.

Docker

docker build -t db-mcp .
docker run -i db-mcp

Für den lokalen Betrieb des Servers nicht erforderlich (die obige Client-Konfiguration erwartet einen lokalen node-Prozess), aber als alternative Möglichkeit zur Überprüfung bzw. Ausführung bereitgestellt.