db-mcp-server

Ein lokaler MCP-Server, der einem KI-Codierungsassistenten (z. B. Claude Code) zugangsdatenisolierten Zugriff auf Ihre PostgreSQL-Datenbanken gewährt. Der Assistent sendet nur SQL und erhält nur Zeilen — Datenbank-Benutzernamen, Passwörter und SSH-Schlüssel gelangen nie in den Kontext des Modells oder das Gesprächsprotokoll.

Warum

Die Verbindung eines KI-Assistenten mit einer Datenbank bedeutet normalerweise, Verbindungszeichenfolgen und Passwörter an einem Ort zu platzieren, an dem das Modell (und sein Protokoll) sie lesen kann. Dieser Server hält diese Grenze ein: Er besitzt die verschlüsselten Anmeldedaten und die SSH-Tunnel, stellt eine kleine, nur-SQL-Werkzeugoberfläche bereit und ist standardmäßig schreibgeschützt.

Related MCP server: Postgres Scout MCP

So funktioniert es

• Katalog (registry.yaml) — nicht-geheime Weiterleitung. Organisiert als Kunden → Umgebungen → Dienste; jeder Dienst ist einem Datenbanknamen und einem secret_ref (einem Zeiger in den Tresor — niemals einer Anmeldeinformation) zugeordnet.

• Tresor (vault.enc) — AES-256-GCM mit einem aus scrypt abgeleiteten Schlüssel. Enthält die DB-Anmeldedaten, die beim Start einmalig mit einer Passphrase in den Speicher entschlüsselt werden.

• Tunnel-Pool — ein SSH-Tunnel pro (Kunde, Umgebung) über sshtunnel, gebunden an einen ephemeren 127.0.0.1-Port.

• Ausführer — psycopg. run_query läuft in einer PostgreSQL READ ONLY-Transaktion (die Engine lehnt jeden Schreibvorgang ab); run_write_query erfordert confirm=true.

Installation

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1   (bash: source .venv/Scripts/activate)
pip install -e ".[dev]"

Konfiguration

Die Konfiguration erfolgt über Umgebungsvariablen; Standardwerte werden relativ zum Projektstamm aufgelöst.

Bereitstellung (Erstsetup)

1. Kopieren Sie die Vorlage und füllen Sie echte Werte ein:

   cp bootstrap.example.yaml bootstrap.yaml

2. Legen Sie Ihre SSH-Privatekeys in keys/ ab (Dateinamen müssen den pem_key-Feldern im Katalog entsprechen).

3. Generieren Sie den nicht-geheimen Katalog und den verschlüsselten Tresor (fragt nach der Passphrase, die Sie zum Ausführen des Servers wiederverwenden):

   python -m db_mcp_server.bootstrap --dry-run   # preview, writes nothing
   python -m db_mcp_server.bootstrap             # writes registry.yaml + vault.enc
   python -m db_mcp_server.vault_admin verify     # expect {"ok": true}

bootstrap.yaml enthält Klartext-Anmeldedaten — es ist git-ignoriert; löschen Sie es oder bewahren Sie es offline auf, sobald der Tresor existiert.

Befehlszeilenwerkzeuge

(Konsolenbefehle existieren nach pip install -e .; die Form python -m db_mcp_server.<Modul> funktioniert immer.)

Dem Assistenten bereitgestellte Werkzeuge

• list_databases() — der Katalog (Kunden → Umgebungen → Dienste); keine Geheimnisse.

• run_query(customer, environment, service, sql, max_rows?) — schreibgeschützt.

• run_write_query(customer, environment, service, sql, confirm) — gesteuerter Schreibzugriff.

Domänenfehler werden als strukturiertes {error_code, message} zurückgegeben, nicht als Ausnahme, sodass der Assistent reagieren kann.

Bei einem MCP-Client registrieren

Beispiel .mcp.json (Pfade anpassen). Verwenden Sie ${DB_MCP_PASSPHRASE}, damit die Passphrase aus der Shell gelesen wird, statt in die Datei geschrieben zu werden:

{
  "mcpServers": {
    "db": {
      "command": "/absolute/path/to/db-mcp-server/.venv/Scripts/python.exe",
      "args": ["-m", "db_mcp_server.server"],
      "env": {
        "DB_MCP_PASSPHRASE": "${DB_MCP_PASSPHRASE}"
      }
    }
  }
}

Sicherheitshinweise

• vault.enc, keys/, bootstrap.yaml, *.env und *.pem sind git-ignoriert — committen Sie sie niemals.

• Die Tresor-Passphrase wird über DB_MCP_PASSPHRASE (oder eine Eingabeaufforderung) bereitgestellt — niemals in registry.yaml, argv oder Protokollen gespeichert.

• db-vault liest das DB-Passwort über eine versteckte Eingabeaufforderung (getpass), niemals über argv.

• run_query ist auf PostgreSQL-Engine-Ebene schreibgeschützt; Schreibvorgänge erfordern confirm=true.

Tests

pip install -e ".[dev]" && python -m pytest -q

Der DB-Integrationstest wird übersprungen, es sei denn, DB_MCP_TEST_DSN zeigt auf ein erreichbares PostgreSQL.

Roadmap (nicht in diesem Build)

Persistenter Prüfpfad, Mehrbenutzerbetrieb, externe Secret-Manager-Anbindung, Schema-Introspektionswerkzeuge und eine Berechtigungs-Denylist, um die Anmeldedatenisolation zu einer harten Grenze zu machen.