Dbeaver Ui

Ein MCP-Server, der einen KI-Assistenten mit einer laufenden DBeaver-Installation verbindet.

Der Unterschied zu den vorhandenen DBeaver-MCP-Servern: Die lesen die Verbindungsdaten aus dem DBeaver-Workspace und reden dann headless mit der Datenbank — DBeaver selbst bleibt außen vor. Dieser Server macht beides:

• Er recherchiert über die dbvr-CLI — Metadaten und Abfrageergebnisse gehen zurück ans Modell.
• Er zeigt das Ergebnis im DBeaver-Fenster des Nutzers — richtige Verbindung, richtiger SQL-Editor, ausgeführt, Ergebnisraster gefüllt.

„Zeig mir den Kunden, dessen Payment gestern fehlgeschlagen ist.“

Der Assistent sucht über db_query die passende Zeile, und legt sie dann mit dbeaver_open_table in deinem DBeaver auf den Schirm — wo du mit Filtern, Sortieren und Exportieren normal weiterarbeitest.

Wie es funktioniert

Assistent
   │
   ├─ db_*              ──► dbvr CLI ──────────────► Datenbank    (Daten fürs Modell)
   │
   └─ dbeaver_open_*    ──► DBeaver-CLI ───────────► DBeaver-GUI  (Daten für den Menschen)
                                -reuseWorkspace
                                -bringToFront
                                -con "id=…|create=false"
                                -f query.sql
                            + Strg+Enter über die Fenstersteuerung

Das Öffnen nutzt ausschließlich die dokumentierte DBeaver-Kommandozeile. Einzige Ausnahme ist das automatische Ausführen: Nach -f query.sql steht die Abfrage im Editor, ist aber nicht ausgeführt — dafür braucht es Strg+Enter, und das geht nur über die Fenstersteuerung des jeweiligen Systems.

Voraussetzungen

DBeaver	beliebige Edition. Die ausführbare Datei wird automatisch gesucht.
Python	3.11 oder neuer.
dbvr	optional, aber empfohlen — ohne dbvr gibt es nur die GUI-Werkzeuge, keine Daten fürs Modell. Download

Der Server muss auf derselben Maschine wie DBeaver laufen. Der Assistent darf woanders sein (dann HTTP-Transport).

Plattformen

Das Öffnen im Editor läuft über die DBeaver-Kommandozeile und funktioniert überall — die Parameter -con, -f, -reuseWorkspace und -bringToFront sind auf allen drei Systemen dokumentiert. Nur das automatische Ausführen braucht Zugriff auf die Fenstersteuerung:

System	Öffnen	Automatisch ausführen
Windows	✅	✅ über user32 (keine Zusatzpakete)
Linux (X11)	✅	✅ über xdotool (apt install xdotool)
Linux (Wayland)	✅	❌ — wird erkannt und gemeldet
macOS	✅	❌ — noch kein Backend

Wo das Ausführen nicht geht, meldet das Werkzeug „geöffnet, nicht ausgeführt“, und im Editor genügt Strg+Enter.

Installation

git clone https://github.com/Getty/dbeaver-ui-mcp
cd dbeaver-ui-mcp
pip install -e .

Prüfen, ob alles gefunden wird:

dbeaver-ui-mcp --status

DBeaver-UI-MCP — Installationsbericht

  platform               win32
  dbeaver_executable     C:\Program Files\DBeaver\dbeaverc.exe
  dbvr_executable        C:\Program Files\dbvr\dbvr.exe
  workspace              C:\Users\du\AppData\Roaming\DBeaverData\workspace6
  connection_count       7
  read_only              True
  autoexecute_allowed    True
  autoexecute_backend    windows/user32
  autoexecute_usable     True
  projects               General, Kundenprojekt

Alles gefunden.

Wird etwas nicht gefunden, steht unter „Nicht gefunden“, was fehlt — die passenden Umgebungsvariablen stehen weiter unten.

Anbinden an einen Assistenten

Lokal (Assistent auf derselben Maschine wie DBeaver)

Claude Desktop, claude_desktop_config.json:

{
  "mcpServers": {
    "dbeaver": {
      "command": "dbeaver-ui-mcp"
    }
  }
}

Claude Code:

claude mcp add dbeaver -- dbeaver-ui-mcp

Remote (Assistent läuft woanders)

Auf der Maschine mit DBeaver:

dbeaver-ui-mcp --transport http --host 0.0.0.0 --port 8000 --token DEIN_GEHEIMES_TOKEN

Beim Assistenten:

{
  "mcpServers": {
    "dbeaver": {
      "type": "http",
      "url": "http://arbeitsrechner.lan:8000/mcp",
      "headers": { "Authorization": "Bearer DEIN_GEHEIMES_TOKEN" }
    }
  }
}

Ohne --token warnt der Server beim Start — und das zu Recht: Wer den Port erreicht, kann Abfragen auf deinen Datenbanken ausführen.

Werkzeuge

Daten fürs Modell

Werkzeug	Zweck
db_list_connections	Gespeicherte DBeaver-Verbindungen mit Name und ID
db_query	SQL ausführen, Ergebnis als JSON oder CSV zurück
db_list_schemas	Schemata einer Verbindung
db_list_tables	Tabellen, optional je Schema
db_describe_table	DDL einer Tabelle

Anzeige für den Menschen

Werkzeug	Zweck
dbeaver_open_query	SQL im Editor öffnen und ausführen
dbeaver_open_table	Tabellendaten mit Filter und Sortierung anzeigen
dbeaver_open_console	Leere SQL-Konsole auf einer Verbindung
dbeaver_bring_to_front	DBeaver-Fenster nach vorn

Diagnose

Werkzeug	Zweck
dbeaver_status	Was wurde gefunden, was fehlt
dbvr_help	Hilfe der installierten dbvr-Version

dbvr_help ist bewusst dabei: Die Befehlsoberfläche von dbvr unterscheidet sich zwischen Versionen, und das dbvr-README weist ausdrücklich darauf hin. Scheitert ein db_*-Werkzeug an einer Option, kann der Assistent selbst nachsehen, statt zu raten.

Konfiguration

Alles per Umgebungsvariable oder Kommandozeile; die Kommandozeile hat Vorrang.

Variable	Vorgabe	Bedeutung
DBEAVER_MCP_DBEAVER_PATH	automatisch	Pfad zu dbeaverc.exe bzw. dbeaver-ce
DBEAVER_MCP_DBVR_PATH	automatisch	Pfad zur dbvr-CLI
DBEAVER_MCP_WORKSPACE	automatisch	workspace6-Verzeichnis
DBEAVER_MCP_READ_ONLY	true	Nur lesende Statements zulassen
DBEAVER_MCP_ALLOW_AUTOEXECUTE	true	Strg+Enter senden dürfen
DBEAVER_MCP_DEFAULT_LIMIT	200	Zeilenbegrenzung für generierte SELECTs
DBEAVER_MCP_DBVR_TIMEOUT	60	Sekunden für dbvr-Aufrufe
DBEAVER_MCP_SCRATCH_DIR	%TEMP%\dbeaver-ui-mcp bzw. /tmp/dbeaver-ui-mcp	Ablage der erzeugten .sql-Dateien
DBEAVER_MCP_TOKEN	—	Bearer-Token für HTTP

Sicherheit — und was der Schutz nicht leistet

Read-only ist die Vorgabe. Der Guard prüft jedes Statement, nicht nur das erste, und lässt sich nicht durch angehängte Semikolons oder Kommentare täuschen (SELECT 1; -- x\nDROP TABLE … wird abgelehnt). Aufheben lässt er sich nur bewusst mit --allow-write.

Bezeichner werden gequotet. Schema- und Tabellennamen gehen dialektgerecht durchs Quoting ("…", `…`, […]), schließende Zeichen werden verdoppelt. Ein Tabellenname wie orders"; DROP TABLE users; -- bleibt vollständig ein Bezeichner.

Drei Dinge, die dieser Schutz ausdrücklich nicht leistet:

1. where und order_by sind rohe SQL-Ausdrücke. Sie lassen sich nicht quoten, ohne sie unbrauchbar zu machen. Der Read-only-Guard prüft das fertige Statement — aber ein Modell kann dort beliebiges Lese-SQL unterbringen, inklusive Unterabfragen auf andere Tabellen.
2. Der Guard ist kein Datenbankschutz. Er läuft im Server, nicht in der Datenbank. Wer wirklich Read-only will, gibt der DBeaver-Verbindung einen Datenbankbenutzer mit Leserechten. Das ist die einzige Grenze, die zählt.
3. Der Assistent erbt deine Datenbankrechte. Der Server nutzt die in DBeaver hinterlegten Zugangsdaten. Ein Assistent mit Zugriff auf diesen Server kann alles, was du in DBeaver könntest.

Zugangsdaten liest dieser Server übrigens nicht: Passwörter liegen verschlüsselt in credentials-config.json, und das Entschlüsseln ist nicht Aufgabe der Brücke. DBeaver und dbvr bringen ihre eigenen mit.

Grenzen

Das automatische Ausführen kann fehlschlagen. Beide Systeme wehren sich dagegen, dass ein Hintergrundprozess den Fokus an sich reißt. Unter Windows nutzt der Server den üblichen Weg darum herum (ALT-Anschlag plus AttachThreadInput), unter Linux xdotool windowactivate --sync. Ein Vollbildfenster oder eine Anwendung mit erhöhten Rechten kann den Fokuswechsel trotzdem blockieren.

Wichtig dabei: In dem Fall wird nichts gesendet. Vor jedem Tastendruck prüft der Server, dass das DBeaver-Fenster wirklich vorne liegt und der erwartete Dateiname im Fenstertitel steht. Trifft das nicht zu, meldet das Werkzeug ehrlich „geöffnet, nicht ausgeführt“ — statt Strg+Enter an ein beliebiges anderes Programm zu schicken.

Statt einer festen Wartezeit pollt der Server den Fenstertitel, bis der Dateiname auftaucht. Ein laufendes DBeaver reagiert damit in Millisekunden, ein kalt startendes bekommt bis zu 15 Sekunden.

Unter Linux wird bewusst nicht xdotool key --window verwendet, das die Tasten ohne Fokuswechsel zustellen würde: DBeaver ist eine SWT/Java-Anwendung, und Java-Oberflächen verwerfen über XSendEvent zugestellte Ereignisse häufig als synthetisch.

Was die CLI nicht kann: Einen konkreten Tabellen-Data-Editor mit gesetztem DBeaver-Filter öffnen, einen bestimmten Untertab wählen, eine Zeile fokussieren oder die Darstellung auf Record View stellen. Dafür gibt es keine dokumentierte Schnittstelle. Der hier gewählte Weg — ein generiertes SELECT im SQL-Editor — deckt den praktischen Nutzen ab, sieht aber anders aus als ein Doppelklick auf die Tabelle im Navigator.

Die saubere Endstufe dafür wäre ein kleines DBeaver-Plug-in (Eclipse RCP), das auf einem lokalen Port oder einer Named Pipe lauscht und intern den echten Objekteditor öffnet. Die Werkzeug-Signaturen hier sind bereits darauf zugeschnitten: dbeaver_open_table nimmt schema/table/where/order_by entgegen — ein Plug-in könnte dieselbe Anfrage bedienen, ohne dass sich für den Assistenten etwas ändert.

Entwicklung

pip install -e ".[dev]"
pytest
ruff check .

Die Tests laufen auf jedem System, ohne DBeaver und ohne dbvr: Statt der echten Programme kommt eine Attrappe zum Einsatz, die ihre Argumente protokolliert. Damit ist der ganze Weg abgedeckt — Werkzeugaufruf, Verbindungsauflösung, SQL-Erzeugung, Kommandozeilenaufbau. Die Bearer-Authentifizierung wird gegen einen echten HTTP-Server geprüft.

Aufbau der Quellen:

Datei	Zweck
server.py	Werkzeugdefinitionen, Authentifizierung
workspace.py	data-sources.json lesen, Verbindungen auflösen
dbeaver_cli.py	Kommandozeile für DBeaver bauen und aufrufen
dbvr.py	dbvr aufrufen und Ausgabe parsen
sqlgen.py	SQL erzeugen, Bezeichner quoten, Read-only-Guard
ui/	Fenstersteuerung — windows.py (user32), linux.py (xdotool)

Ein Backend für ein weiteres System braucht nur die vier Methoden aus dem Backend-Protokoll in ui/__init__.py; die Ablaufsteuerung (warten, fokussieren, prüfen, senden) ist geteilt.

Lizenz

MIT