database-mcp

SQL-Datenbank-MCP-Server mit echtem serverseitigem Ergebnis-Paging – die Funktion, die kein etablierter Datenbank-MCP-Server hat (DBHub begrenzt Zeilen, Googles MCP Toolbox liefert alles zurück, mcp-alchemy kürzt bei 4000 Zeichen ab).

PostgreSQL-Referenzimplementierung.

Warum

Jeder bestehende SQL-MCP-Server kürzt entweder große Ergebnisse oder wirft sie komplett in den Kontext des Modells. Die MCP-Spezifikation paginiert nur Listen-Operationen (tools/list), nicht Tool-Ergebnisse. database-mcp schließt diese Lücke:

• Eine Abfrage wird einmal als serverseitiger PostgreSQL-Cursor ausgeführt (DECLARE/FETCH FORWARD) innerhalb einer gehaltenen Transaktion.

• Jedes fetch(cursor) fährt genau dort fort, wo die letzte Seite endete – keine erneute Ausführung, kein OFFSET-Rescan, und der MVCC-Snapshot hält das Ergebnis auch bei gleichzeitigen Schreibvorgängen stabil.

• Seiten werden durch Zeilen (page_size) und gerenderte Bytes (max_page_bytes) begrenzt; überdimensionierte Zellen werden mit einem expliziten Marker gekürzt.

• Gehaltene Cursor sind begrenzt: max. N gleichzeitig (LRU-Eviction), TTL-Idle- Eviction, plus idle_in_transaction_session_timeout als serverseitige Absicherung. Erschöpfte Cursor schließen sich automatisch.

Related MCP server: pgsql-mcp

Verbindungsprofile – von der KI zur Laufzeit verwaltet

Verbindungen sind benannte Profile, gespeichert in ~/.config/database-mcp/profiles.json (chmod 600). Die KI kann sie über Tools hinzufügen, ändern, testen und entfernen – ohne Serverneustart:

• profile_add(name, dsn, allow_writes=false, description, make_default, test=true)

• profile_remove(name) · profile_test(name) · profiles()

• jedes Abfragetool akzeptiert einen optionalen profile-Parameter; das Standardprofil wird verwendet, wenn keins angegeben ist.

Profile sind standardmäßig schreibgeschützt (Sitzungsebene default_transaction_read_only); Schreibvorgänge benötigen ein explizites allow_writes=true-Profil.

SSH-Brücken

Ein Profil kann eine Datenbank erreichen, die nur über SSH zugänglich ist (das klassische "Postgres lauscht auf localhost eines entfernten Hosts"-Setup):

profile_add(name="prod", dsn="postgresql://app@dbhost:5432/app",
            ssh_host="dbhost")

• Der Tunnel ist ein System-ssh-Subprozess (-N -L, BatchMode, Keepalives) – Ihre ~/.ssh/config, Schlüssel und Agent gelten unverändert. Die Authentifizierung muss nicht-interaktiv funktionieren.

• ssh_remote_host/ssh_remote_port standardmäßig auf den Host/Port der DSN, wie vom SSH-Host aus gesehen; wenn die DSN-Host gleich dem SSH-Host ist, wird standardmäßig 127.0.0.1 verwendet (der übliche Fall).

• Tunnel starten lazy, werden bei jeder Nutzung auf Gesundheit geprüft und automatisch neu aufgebaut. Wenn ein Tunnel mitten im Paging stirbt, werden seine Cursor mit einer klaren Fehlermeldung ungültig gemacht und die nächste Abfrage verbindet sich neu.

• Multiplexing (ControlMaster) ist für Tunnelverbindungen explizit deaktiviert, sodass die Lebensdauer des Tunnels genau der Lebensdauer des Subprozesses entspricht.

Tools

Ergebnisse sind kompaktes JSON – Spalten einmal, Zeilen als Arrays – etwa die Hälfte der Tokens des Zeilen-Dict-Formats, das andere Server ausgeben. query gibt auch estimated_rows zurück (Planerschätzung über EXPLAIN), damit das Modell weiß, worauf es paginiert.

Installation & Ausführung

uv pip install -e .
database-mcp --dsn postgresql://user@host:5432/db      # registers profile "default"
database-mcp                                           # start empty, add profiles at runtime

Claude-Code-Registrierung:

claude mcp add database -- database-mcp --dsn postgresql://user@host:5432/db

Optionen: --profiles FILE, --allow-writes, --page-size 50, --max-page-size 500, --max-page-bytes 32000, --max-cell 400, --cursor-ttl 300, --max-cursors 4, --statement-timeout 30, --keepalive 120, --connect-timeout 5. Env: DATABASE_MCP_DSN / DATABASE_URL, DATABASE_MCP_PROFILES.

Umgang mit veralteten Verbindungen

Tote Verbindungen werden auf jeder Ebene schnell erkannt, statt zu hängen:

• SSH-Tunnel: ServerAliveInterval = --keepalive (Standard 2 Min.) mit ServerAliveCountMax=1 – ein verpasster Probe beendet den Tunnelprozess, den der Engine-Manager bei der nächsten Nutzung erkennt und lazy neu aufbaut.

• DB-Verbindungen: TCP-Keepalives (keepalives_idle = --keepalive, Proben alle 10 s, 3 Fehlversuche) erkennen tote Peers in ~30 s – einschließlich gepinnter Cursor-Verbindungen außerhalb des Pools.

• Pool-Checkout-Prüfung: Jede ausgegebene Verbindung wird mit einem günstigen Round-Trip validiert; eine veraltete wird verworfen und transparent ersetzt – der Aufrufer sieht den Fehler nie. Leere Pool-Verbindungen werden nach --keepalive Sekunden recycelt; Verbindungsversuche schlagen nach --connect-timeout (Standard 5 s) fehl, statt des ~2 Min. TCP-Standards.

Tests

uv pip install -e '.[dev]'
pytest            # needs a local PostgreSQL (DBMCP_TEST_DSN to override)

Lizenz

MIT