Gatekeeper
Deine Agenten schlagen das SQL vor. Du entscheidest, was läuft.
Gatekeeper ist eine von Menschen kontrollierte Brücke zwischen KI-Agenten und deiner Datenbank. Ein Agent schlägt über MCP eine Abfrage vor; standardmäßig läuft nichts, bis du sie in Beekeeper Studio anhand des SQL-Texts vor der Ausführung freigibst. Die Abfrage läuft dann über die Verbindung, die Beekeeper bereits hält, und die Zeilen gehen an den Agenten zurück.
Standardmäßig nur lesend. Ein Schreibzugriff läuft nur in einem Modus, den du selbst im Plugin aktivierst, und dieser Modus ist flüchtig. Der Agent bekommt nie deine Datenbank-Zugangsdaten.
Musik von #Uppbeat
Shine von Swoop: https://uppbeat.io/t/swoop/shineTipp
Auto-Modus (Beta): Aktiviere gezielt die automatische Freigabe für eine eng begrenzte Teilmenge von PostgreSQL-Lesezugriffen. Lokale Prüfungen und Jev müssen beide bestehen. Einrichtung, Provider-Freigabe und Einschränkungen findest du unter Auto-Modus.
Die drei Bausteine
| Baustein | Was er macht | Wo er läuft |
|---|---|---|
| Beekeeper Studio Plugin | Zeigt jede vorgeschlagene Abfrage, stuft ihr Risiko ein und führt sie nach deiner Freigabe auf deiner Verbindung aus | In Beekeeper Studio |
| MCP-Server | Die Seite für den Agenten: die Tools, mit denen ein Agent eine Abfrage vorschlägt und ihr Ergebnis abholt | Auf deinem Rechner, gestartet von deinem Agenten |
| Agent-Skill | Bringt jedem Agenten bei, diese Tools richtig zu nutzen | Im Skills-Ordner deines Agenten |
Sie werden gemeinsam unter einer Version ausgeliefert und sind nur zusammen sinnvoll: Das Plugin ohne Server hat nichts freizugeben, der Server ohne Plugin hat niemanden zum Fragen.
Warum
- Standardmäßig manuelle Freigabe. Der Auto-Modus ist optional und flüchtig. Die Quelle der Freigabe und, falls vorhanden, der bewertende Prüfer werden protokolliert.
- Keine Datenbank-Zugangsdaten verlassen Beekeeper. Abfragen laufen über die bereits authentifizierte Verbindung. Verbinde Beekeeper mit einem Read-Replica oder einer Nur-Lese-Rolle als harte Absicherung.
- Das Risiko wird eingestuft, nicht angenommen. Ein dialektbewusster Parser ordnet jede Abfrage als lesend, schreibend oder destruktiv ein, und der Freigabe-Button bleibt gesperrt, bis der passende Modus aktiviert ist.
So funktioniert's
MCP client Gatekeeper server (127.0.0.1) Beekeeper Studio
┌────────────────────┐ MCP ┌───────────────────────────┐ fetch ┌────────────────────┐
│ submit_query(sql) │ ───────► │ MCP server + HTTP broker │ ◄─────── │ Plugin (iframe) │
│ get_query_result() │ ◄─────── │ SQLite lease queue + audit│ poll │ 1. show SQL │
│ cancel_query() │ │ /pending /executing │ ───────► │ 2. human approves │
│ │ │ /result /lease/renew │ result │ 3. runQuery() │
└────────────────────┘ └───────────────────────────┘ │ 4. post result │
└────────────────────┘
- Der Agent reicht einen Vorschlag ein und erhält sofort eine Request-ID zurück. Nichts blockiert.
- Das Plugin fragt den lokalen Broker ab, übernimmt den Vorschlag per Lease und zeigt das SQL an.
- Du gibst frei oder lehnst ab. Bei Freigabe führt Beekeeper die Abfrage auf deiner Verbindung aus.
- Das Plugin meldet das Ergebnis zurück, und der Agent holt es ab, sobald es bereit ist.
Das Plugin läuft in einem sandboxed iframe und kann daher nie eingehende Verbindungen annehmen: Stattdessen fragt es den Broker ab. Diese eine Einschränkung erklärt den gesamten Aufbau. Alle Details unter Architektur.
Los geht's
Voraussetzungen: Beekeeper Studio >= 5.4 und Node >= 22. Wenn du Claude Code oder Codex CLI nutzt, hast du Node bereits. Es gibt keinen Hintergrunddienst zu installieren: Dein Agent startet den Server, wenn seine Sitzung beginnt, und beendet ihn, wenn sie endet.
Warnung
Vorerst nur macOS. Gatekeeper wird auf macOS entwickelt und getestet. Windows und Linux sind noch nicht getestet, betrachte sie also als nicht unterstützt, bis jemand Rückmeldung gibt. Nichts im ausgelieferten Code ist macOS-spezifisch (der Server ermittelt Pfade über dein Home-Verzeichnis, das Plugin ist eine normale Beekeeper-Webview), daher sollten beide funktionieren – aber „sollten“ ist nicht verifiziert. Berichte von beiden Plattformen sind sehr willkommen.
Schnellinstallation
Ein eigener Skill richtet alles für dich ein: das Plugin, den MCP-Server, den Begleit-Skill und das Pairing. Füge die Skills zu deinem Agenten hinzu:
npx skills add Gldywn/gatekeeper
Bitte dann deinen Agenten, Gatekeeper zu installieren, oder führe den Skill direkt aus:
/install-gatekeeper
Er erledigt jeden Schritt, den deine Umgebung zulässt, und gibt dir für den Rest eine kurze Checkliste, etwa Beekeeper neu zu starten. Später prüft /update-gatekeeper alle drei Bausteine und aktualisiert nur, was veraltet ist.
Manuelle Installation
Lieber von Hand, oder willst du genau sehen, was passiert?
Wichtig
Noch nicht in Beekeepers Plugin-Registry. Eine Einreichung bei den Beekeeper-Maintainern läuft. Bis sie gemergt ist, listet Manage Plugins Gatekeeper nicht und die Ein-Klick-Installation ist nicht verfügbar, daher ist Schritt 1 unten der manuelle Weg. Sonst ändert sich nichts.
1. Installiere das Plugin in Beekeeper Studio. Lade gatekeeper-<version>.zip aus dem neuesten Release herunter, entpacke es in Beekeepers Plugin-Ordner und starte Beekeeper neu:
| OS | Plugin-Ordner |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/plugins/ |
| Linux | ~/.config/beekeeper-studio/plugins/ |
| Windows | %APPDATA%\beekeeper-studio\plugins\ |
Der entpackte Ordner muss exakt
gatekeeperheißen. Das Zip entpackt sich zugatekeeper-<version>/, benenne ihn also nach dem Entpacken um. Beekeeper gleicht den Ordnernamen mit der Plugin-ID ab und überspringt jeden abweichenden Ordner kommentarlos: kein Fehler, kein Eintrag in Manage Plugins, nichts zum Anklicken. Das ist der häufigste Grund, warum eine manuelle Installation scheinbar nichts bewirkt.
2. Registriere den MCP-Server bei deinem Agenten. Das ist zugleich die Server-Installation: npx lädt ihn beim ersten Start herunter und cached ihn.
# Claude Code
claude mcp add gatekeeper --scope user -- npx -y @gldywn/gatekeeper-mcp-server
# Codex CLI, in ~/.codex/config.toml
[mcp_servers.gatekeeper]
command = "npx"
args = ["-y", "@gldywn/gatekeeper-mcp-server"]
Lieber pnpm? pnpm dlx @gldywn/gatekeeper-mcp-server ist das direkte Gegenstück zur npx-Zeile. Um das Paket nur einmal statt bei jedem Agentenstart aufzulösen, installiere es mit pnpm add -g @gldywn/gatekeeper-mcp-server und verweise deinen Client auf das gatekeeper-mcp-server-Binary, das dabei in deinem PATH landet.
Jeder Client, der .mcp.json liest, kann .mcp.json.example direkt verwenden. Pinne die Version (@gldywn/gatekeeper-mcp-server@<version>), wenn du Upgrades lieber prüfst, statt sie einfach zu bekommen: Ohne Pin löst npx bei jedem Agentenstart das neueste Release auf. Das hält dich aktuell, bedeutet aber, dass sich ein Prozess mit Zugang zu deiner Datenbank unbemerkt ändert.
3. Installiere den Agent-Skill.
npx skills add Gldywn/gatekeeper
Die CLI ist interaktiv: Sie fragt, für welche Agenten installiert werden soll und ob global. Sie funktioniert mit Claude Code, Codex, Cursor und den übrigen.
4. Kopple das Plugin, einmal pro Rechner. Starte deinen Agenten und bitte ihn um etwas, das die Datenbank braucht. Solange das Plugin nicht gekoppelt ist, antwortet jedes Gatekeeper-Tool mit einem 6-stelligen Code: Gib diesen Code im Plugin ein (Tools -> Gatekeeper). Der Code ist einmalig gültig, hält etwa fünf Minuten, und http://127.0.0.1:9999/pair zeigt immer den aktuellen. Das übergebene Capability-Token wird in Beekeepers verschlüsseltem Speicher abgelegt.
Auf diesem Port antwortet nichts, bis dein Agent den Server mindestens einmal gestartet hat. Öffnest du das Plugin vorher, sagt es dir das, statt ein Pairing-Feld anzuzeigen, das es nicht bedienen kann.
5. Leg los. Bitte deinen Agenten um etwas, das die Datenbank braucht. Er schlägt SQL vor, die Abfrage erscheint im Plugin, du gibst frei, und die Zeilen gehen an den Agenten zurück. Lesezugriffe funktionieren sofort; ein Schreibzugriff läuft erst, wenn du den Write- oder Destructive-Modus aktivierst.
Wie du aus dem Quellcode baust, steht unter Entwicklung.
Wenn das Plugin nicht auftaucht
Beekeeper wird mit gesperrtem Plugin-System ausgeliefert, daher kann eine frische Installation ein Drittanbieter-Plugin komplett ignorieren. Prüfe drei Dinge, in dieser Reihenfolge:
1. Der Ordnername. Exakt gatekeeper, nicht gatekeeper-0.1.1. Abweichungen werden wie oben beschrieben stillschweigend übersprungen.
2. Das Plugin-System ist aktiviert. Beekeepers Standardeinstellungen setzen pluginSystem.disabled = true, mit einer Allowlist, die nur die zwei eigenen Plugins enthält. Füge das hier zu deiner User-Config hinzu und starte neu:
[pluginSystem]
disabled = false
3. Community-Plugins sind aktiviert. communityDisabled = true ist ebenfalls Standard und deaktiviert jedes Plugin, das Beekeeper als Community führt. Zeigt der Plugin-Manager „Community plugins are disabled via configuration“, füge communityDisabled = false im selben Block hinzu.
| OS | User-Config-Datei |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/user.config.ini |
| Linux | ~/.config/beekeeper-studio/user.config.ini |
| Windows | %APPDATA%\beekeeper-studio\user.config.ini |
Zugriffsmodi
Standardmäßig braucht jede Abfrage einen menschlichen Klick auf ihren Text. Der Ausführungsmodus bestimmt, welche Risikoklassen laufen dürfen. Der Auto-Modus ist davon getrennt und erzwingt, solange er aktiv ist, Read.
| Modus | Erlaubt | Aktiviert durch |
|---|---|---|
| Read (Standard) | SELECT und Co. |
Nichts zu tun |
| Write | INSERT, UPDATE |
Dich, im Plugin, mit einer zweiten Bestätigung |
| Destructive | DELETE, DROP, TRUNCATE, ALTER |
Dich, im Plugin, mit einer zweiten Bestätigung |
Der aktivierte Modus liegt nur im Arbeitsspeicher, wird nie gespeichert und springt bei einem Verbindungswechsel oder erneutem Pairing auf Read zurück. Das Plugin stuft die Abfrage im Moment der Ausführung neu ein und prüft erneut, daher wirken Aktivieren und Deaktivieren sofort.
Die Karte liest die Abfrage für dich, sodass ein Blick zur Entscheidung reicht statt sorgfältigem Analysieren. Das SQL kommt formatiert und hervorgehoben an, unsichtbare und richtungsumkehrende Zeichen werden als explizite Markierungen angezeigt – was du liest, ist was läuft. Eine schreibende oder destruktive Anweisung trägt ein farbiges Klassen-Badge und nennt ihr Verb und ihre Zieltabellen, und eine Anweisung, die der Parser nicht lesen kann, sagt das in dauerhaftem Text und wird als destruktiv behandelt.
Unter dem SQL nennt eine Anmerkung die Tabellen, die die Abfrage liest, und die sensiblen Spalten darin: Personendaten in einer Akzentfarbe, Firmen- und Geschäftsdaten in einer anderen, ein sensibler Wert wird auch markiert, wenn er nur in einem WHERE-Filter vorkommt, und ein SELECT * wird gegen die echten Spalten aufgelöst, damit sich nichts hinter dem Stern versteckt. Ein Punkt am Datenbank-Icon im Header zeigt, ob die letzte Verbindungsprüfung bestanden wurde, und das Icon öffnet die Details: diese Prüfung, dann die drei Nur-Lese-Ebenen (der aktivierte Modus, die Beekeeper-Verbindung und der Datenbank-Endpunkt). Der Roboter daneben zeigt die Verbindung zum Gatekeeper-Server, an den deine Agenten ihre Abfragen senden. Er ist grün, solange der Server antwortet, gelb beim Verbinden und rot durchgestrichen, wenn er nicht erreichbar ist; beim Hovern siehst du, wann der Server zuletzt geantwortet hat.
Jeder Detektor lässt sich in den Plugin-Einstellungen umschalten, alle laufen auf deinem Rechner, und nichts von dem, was sie finden, wird je an den Agenten gesendet. Sie prüfen Spaltennamen und Wertformen – betrachte sie also als schnellen Hinweis auf das, was einen zweiten Blick verdient, nicht als Beweis, dass eine Abfrage sauber ist. Keine Markierungen können auch bedeuten, dass die Anmerkung nie aufgelöst wurde.
Sicherheit
- Die Schranke sitzt dort, wo ausgeführt wird. Das Plugin ist die einzige Komponente, die eine Abfrage ausführen kann, also sitzen dort der Klassifizierer und die Modusprüfung.
- Capability-Token bei jeder Anfrage. Ohne Token antwortet der Broker mit
401. Es wird beim ersten Start erzeugt, mit0600unter~/.gatekeepergespeichert und vom Plugin in Beekeepers verschlüsseltem Speicher gehalten. - Pairing per Code. Der Broker kann das Plugin nicht von einer beliebigen Webseite unterscheiden, die du besuchst, daher wird das Token über einen Kanal übertragen, den eine Seite nicht beobachten kann: ein einmaliger 6-stelliger Code, den du mit eigenen Augen liest, fünf Minuten gültig und nach fünf Fehlversuchen ungültig.
- Nur Loopback. Der Broker bindet an
127.0.0.1und lehnt unerwarteteHost-Header ab, sodass eine DNS-Rebinding-Seite ein421bekommt. - Begrenzte Ergebnisse, minimales Audit. Weitergeleitete Zeilen sind nach Anzahl und Bytes begrenzt, damit ein großer Lesezugriff nie den Agenten-Kontext flutet. Das agentenseitige Audit speichert die Entscheidung und einen SQL-Digest, nie rohes SQL und nie Zeilen.
Read garantiert nicht null Nebenwirkungen: Ein SELECT kann eine volatile Funktion aufrufen – genau deshalb erfolgt die Freigabe anhand des sichtbaren SQL. SECURITY.md enthält das Bedrohungsmodell, die Vertrauensgrenze beim selben Benutzer, die Aufbewahrungsfristen und die Supply-Chain-Richtlinie.
Dokumentation
| Dokument | Inhalt |
|---|---|
| Architektur | Die zwei Kanäle, die Freigabeschleife, die Lease-Queue, Ergebnisgrenzen |
| MCP-Tools | Jedes Tool, das ein Agent aufrufen kann, das Ticket-Format, der Warte-Vertrag |
| Konfiguration | Umgebungsvariablen und Desktop-Benachrichtigungen |
| Sicherheit | Bedrohungsmodell, Vertrauensgrenze, Aufbewahrung, Supply Chain |
| Entwicklung | Aus dem Quellcode bauen, Dev-Setup, Repo-Struktur, Tech-Stack |
| Releases | Wie aus einem Commit ein Plugin-Release und ein npm-Paket wird |
Entwicklung
pnpm install
pnpm build # both packages
pnpm ci # typecheck + build + test
pnpm dev:link verweist Beekeeper auf deinen Checkout, und pnpm dev startet die Plugin-UI mit Hot Reload. Das komplette Setup inklusive Testdatenbanken findest du unter Entwicklung.