Gatekeeper
SQLを提案するのはエージェント。実行を承認するのはあなたです。
Gatekeeperは、AIエージェントとデータベースの間をつなぐ人間承認型のブリッジです。エージェントはMCP経由でクエリを提案しますが、デフォルトでは、実行前にBeekeeper Studio上でSQLテキストをあなたが承認するまで何も実行されません。承認後、クエリはBeekeeperが既に保持している接続で実行され、結果の行がエージェントに返されます。
デフォルトは読み取り専用です。書き込みは、あなた自身がプラグインで有効化したモードでのみ実行され、そのモードは一時的なものです。エージェントがデータベースの認証情報を持つことはありません。
音楽: #Uppbeat
Shine by Swoop: https://uppbeat.io/t/swoop/shineヒント
オートモード（ベータ）：PostgreSQLの限定的な読み取りクエリについて、自動承認を明示的に有効化できます。ローカルチェックとJevの両方を通過する必要があります。セットアップ、プロバイダー共有、制限事項についてはオートモードをご覧ください。
3つの構成要素
| 構成要素 | 役割 | 実行場所 |
|---|---|---|
| Beekeeper Studioプラグイン | 提案された各クエリを表示し、リスクを分類し、承認後にあなたの接続で実行します | Beekeeper Studio内 |
| MCPサーバー | エージェント側の窓口：エージェントがクエリを提案し、結果を受け取るために呼び出すツール群 | ローカルマシン上（エージェントが起動） |
| エージェントスキル | あらゆるエージェントにツールの適切な使い方を教えます | エージェントのskillsフォルダ内 |
3つは同一バージョンで一緒にリリースされ、組み合わせて初めて役立ちます。サーバーがなければプラグインには承認する対象がなく、プラグインがなければサーバーには確認する相手がいません。
なぜGatekeeperか
- デフォルトは手動承認。オートモードは任意かつ一時的です。承認元と、利用可能な評価者の情報が記録されます。
- データベースの認証情報はBeekeeperの外に出ません。クエリは認証済みの接続を通じて実行されます。確実な安全策として、Beekeeperをリードレプリカや読み取り専用ロールに接続してください。
- リスクは推測せず分類します。方言対応のパーサーが各クエリを読み取り・書き込み・破壊的に分類し、対応するモードが有効になるまで承認ボタンはブロックされたままです。
仕組み
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 │
└────────────────────┘
- エージェントが提案を送信すると、すぐにリクエストIDが返されます。処理はブロックされません。
- プラグインがローカルのブローカーをポーリングし、リースを取得して提案を確保し、SQLを表示します。
- あなたが承認または却下します。承認すると、Beekeeperがあなたの接続でクエリを実行します。
- プラグインが結果を送り返し、準備ができ次第エージェントがそれを受け取ります。
プラグインはサンドボックス化されたiframe内で動作するため、受信接続を受けることができず、代わりにブローカーをポーリングします。この1つの制約が全体の構成を説明しています。詳細はアーキテクチャをご覧ください。
はじめに
前提条件：Beekeeper Studio >= 5.4、Node >= 22。Claude CodeやCodex CLIを使っていれば、Nodeは既にインストール済みです。インストールが必要なバックグラウンドサービスはありません。エージェントがセッション開始時にサーバーを起動し、セッション終了時に終了します。
警告
現時点ではmacOSのみ対応です。GatekeeperはmacOSで開発・テストされています。WindowsとLinuxはまだテストされていないため、報告があるまでは非対応として扱ってください。配布コードにmacOS固有の部分はなく（サーバーはホームディレクトリからパスを解決し、プラグインは標準的なBeekeeperのwebviewです）、どちらも動作すると見込まれますが、検証済みではありません。どちらのプラットフォームからの報告も大歓迎です。
クイックインストール
専用のスキルが、プラグイン、MCPサーバー、付属スキル、ペアリングまですべてセットアップします。エージェントにスキルを追加してください：
npx skills add Gldywn/gatekeeper
その後、エージェントにGatekeeperのインストールを依頼するか、スキルを直接実行します：
/install-gatekeeper
環境が許す限りの手順をすべて実行し、Beekeeperの再起動など残りの作業は短いチェックリストで案内します。後から/update-gatekeeperを実行すると、3つの構成要素をすべて確認し、古いものだけを更新します。
手動インストール
手作業で行いたい場合や、何が起きているかを正確に確認したい場合はこちら。
重要
まだBeekeeperのプラグインレジストリには登録されていません。現在Beekeeperのメンテナーに申請中です。マージされるまでは、Manage PluginsにGatekeeperは表示されず、ワンクリックインストールも利用できないため、以下の手順1が手動の方法となります。それ以外に違いはありません。
1. Beekeeper Studioにプラグインをインストールします。最新リリースからgatekeeper-<version>.zipをダウンロードし、Beekeeperのpluginsフォルダに展開して、Beekeeperを再起動します：
| OS | pluginsフォルダ |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/plugins/ |
| Linux | ~/.config/beekeeper-studio/plugins/ |
| Windows | %APPDATA%\beekeeper-studio\plugins\ |
展開したフォルダ名は正確に
gatekeeperにする必要があります。zipはgatekeeper-<version>/として展開されるため、展開後に名前を変更してください。Beekeeperはフォルダ名をプラグインIDと照合し、一致しないフォルダは何も通知せずにスキップします。エラーも、Manage Pluginsへの表示も、クリックできるものもありません。手動インストールで何も起きないように見える最も多い原因がこれです。
2. エージェントにMCPサーバーを登録します。これがサーバーのインストールも兼ねています。初回起動時にnpxがダウンロードしてキャッシュします。
# 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"]
pnpmを使いたい場合：pnpm dlx @gldywn/gatekeeper-mcp-serverがnpxの行とそのまま同等です。エージェント起動のたびではなく一度だけパッケージを解決したい場合は、pnpm add -g @gldywn/gatekeeper-mcp-serverでインストールし、PATHに追加されるgatekeeper-mcp-serverバイナリをクライアントに指定してください。
.mcp.jsonを読み込むクライアントであれば、.mcp.json.exampleをそのまま使用できます。アップグレードを自動で受け取るより監査したい場合は、バージョンを固定してください（@gldywn/gatekeeper-mcp-server@<version>）。固定しない場合、npxはエージェント起動のたびに最新リリースを解決し直します。常に最新を保てますが、データベースへの経路を持つプロセスが知らないうちに変わることを意味します。
3. エージェントスキルをインストールします。
npx skills add Gldywn/gatekeeper
CLIは対話式で、どのエージェント向けにインストールするか、グローバルにインストールするかを尋ねます。Claude Code、Codex、Cursorなど幅広く対応しています。
4. プラグインをペアリングします（マシンごとに1回）。エージェントを起動し、データベースが必要な作業を依頼します。プラグインがペアリングされるまで、Gatekeeperの各ツールは6桁のコードを返すので、そのコードをプラグイン（Tools -> Gatekeeper）に入力してください。コードは1回限りで約5分間有効です。http://127.0.0.1:9999/pairでは常に現在のコードを確認できます。受け渡されたケイパビリティトークンはBeekeeperの暗号化ストレージに保存されます。
エージェントが一度でもサーバーを起動するまで、このポートは応答しません。それより前にプラグインを開くと、使えないペアリング欄を表示する代わりに、その旨を知らせてくれます。
5. 使ってみましょう。データベースが必要な作業をエージェントに依頼します。エージェントがSQLを提案し、クエリがプラグインに表示され、あなたが承認すると、結果の行がエージェントに返されます。読み取りはすぐに使えます。書き込みは、WriteまたはDestructiveモードを有効にしたときにのみ実行されます。
ソースからのビルド方法は開発に記載されています。
プラグインが表示されない場合
Beekeeperはプラグインシステムがロックされた状態で出荷されるため、新規インストールではサードパーティ製プラグインが完全に無視されることがあります。以下の3点を順番に確認してください：
1. フォルダ名。gatekeeper-0.1.1ではなく、正確にgatekeeperにしてください。前述のとおり、一致しない場合は何も通知されずにスキップされます。
2. プラグインシステムが有効になっていること。Beekeeperの出荷時のデフォルトではpluginSystem.disabled = trueが設定され、許可リストには自社製の2つのプラグインしか含まれていません。ユーザー設定に以下を追加して再起動してください：
[pluginSystem]
disabled = false
3. コミュニティプラグインが有効になっていること。communityDisabled = trueも出荷時のデフォルトで、Beekeeperがコミュニティとして扱うプラグインをすべて無効にします。プラグインマネージャーに「Community plugins are disabled via configuration」と表示される場合は、同じブロックにcommunityDisabled = falseを追加してください。
| OS | ユーザー設定ファイル |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/user.config.ini |
| Linux | ~/.config/beekeeper-studio/user.config.ini |
| Windows | %APPDATA%\beekeeper-studio\user.config.ini |
アクセスモード
デフォルトでは、すべてのクエリでテキストを確認したうえでの人間によるクリックが必要です。実行モードによって、どのリスク分類のクエリを実行できるかが決まります。オートモードはこれとは別で、有効な間はReadのみに固定されます。
| モード | 承認対象 | 有効化の方法 |
|---|---|---|
| Read（デフォルト） | SELECTなど |
操作不要 |
| Write | INSERT, UPDATE |
あなたがプラグイン内で、2段階の確認を経て |
| Destructive | DELETE, DROP, TRUNCATE, ALTER |
あなたがプラグイン内で、2段階の確認を経て |
有効化したモードはメモリ上にのみ保持され、永続化されることはなく、接続の切り替えや再ペアリング時に読み取り専用へリセットされます。プラグインは実行の瞬間に再分類と再チェックを行うため、有効化・無効化は即座に反映されます。
カードがクエリを読み解いてくれるため、入念に解析しなくても一目で判断できます。SQLは整形・ハイライトされた状態で届き、不可視文字や文字方向を反転させる文字は明示的なマーカーとして表示されるので、見たとおりのものが実行されます。書き込みや破壊的なステートメントには色付きの分類バッジが付き、その操作と対象テーブルが表示されます。パーサーが読み取れないステートメントはその旨が常時表示され、破壊的なものとして扱われます。
SQLの下には、クエリが読み取るテーブルとその中の機密性の高いカラムが注記されます。個人データと企業・商用データはそれぞれ別の色で示され、機密値はWHEREフィルターにしか現れない場合でもフラグが付き、SELECT *は実際のカラムに展開されるため、アスタリスクの陰に隠れるものはありません。ヘッダーのデータベースアイコンに付くドットは前回の接続チェックが通ったかどうかを示し、アイコンを開くと詳細が表示されます。そのチェック結果に加え、3つの読み取り専用レイヤー（有効化中のモード、Beekeeperの接続、データベースのエンドポイント）を確認できます。隣のロボットアイコンは、エージェントがクエリを送信するGatekeeperサーバーとの接続状態を示します。サーバーが応答している間は緑、接続中は黄色、到達できない場合は赤の取り消し線で表示され、ホバーするとサーバーが最後に応答した時刻が表示されます。
各検出機能はプラグイン設定で個別にオン/オフでき、すべてローカルマシン上で動作し、検出内容がエージェントに送信されることはありません。カラム名や値の形式で照合するため、クエリが安全である証拠ではなく、再確認すべき箇所をすばやく示す目安として扱ってください。フラグがない場合は、注記の解決自体ができなかった可能性もあります。
セキュリティ
- ゲートは実行と同じ場所にあります。クエリを実行できるのはプラグインだけなので、分類器とモードチェックもそこに置かれています。
- すべてのリクエストにケイパビリティトークン。トークンがなければブローカーは
401を返します。トークンは初回実行時に生成され、~/.gatekeeper配下に0600で保存され、プラグイン側ではBeekeeperの暗号化ストレージに保持されます。 - コードによるペアリング。ブローカーはプラグインとあなたが訪れる任意のWebページを区別できないため、トークンはWebページが観測できない経路で受け渡されます。あなた自身の目で読み取る1回限りの6桁コードで、有効期限は5分、5回間違えると無効になります。
- ループバックのみ。ブローカーは
127.0.0.1にバインドし、想定外のHostヘッダーを拒否するため、DNSリバインディングを狙うページには421が返されます。 - 結果の上限と最小限の監査ログ。転送される行は件数とバイト数で上限が設けられ、大量の読み取りでエージェントのコンテキストがあふれることはありません。エージェント側の監査ログには判断結果とSQLのダイジェストのみが残り、生のSQLや行データは記録されません。
読み取りであっても副作用がゼロとは限りません。SELECTが揮発性関数を呼び出すこともあり、だからこそ承認は表示されたSQLに対して行われます。脅威モデル、同一ユーザーの信頼境界、保持期間、サプライチェーンポリシーについてはSECURITY.mdをご覧ください。
ドキュメント
| ドキュメント | 内容 |
|---|---|
| アーキテクチャ | 2つのチャネル、承認ループ、リースキュー、結果の上限 |
| MCPツール | エージェントが呼び出せる全ツール、チケットの形式、待機の仕様 |
| 設定 | 環境変数とデスクトップ通知 |
| セキュリティ | 脅威モデル、信頼境界、保持期間、サプライチェーン |
| 開発 | ソースからのビルド、開発環境の接続、リポジトリ構成、技術スタック |
| リリース | コミットがプラグインのリリースとnpmパッケージになるまで |
開発
pnpm install
pnpm build # both packages
pnpm ci # typecheck + build + test
pnpm dev:linkでBeekeeperをチェックアウトしたコードに向け、pnpm devでホットリロード付きのプラグインUIを起動します。テスト用データベースを含む完全なセットアップは開発に記載されています。