db-mcp-server

ローカル MCPサーバー で、AIコーディングアシスタント（例: Claude Code）に PostgreSQL データベースへの 認証情報分離 アクセスを提供します。アシスタントは SQL のみを送信し、行のみを受け取ります。データベースのユーザー名、パスワード、SSH キーがモデルのコンテキストや会話のトランスクリプトに入ることはありません。

なぜ

AI アシスタントをデータベースに接続する場合、通常は接続文字列やパスワードをモデル（およびそのトランスクリプト）が読み取れる場所に置く必要があります。このサーバーはその境界を維持します。暗号化された認証情報と SSH トンネルを所有し、SQL のみの小さなツールサーフェスを公開し、デフォルトで読み取り専用です。

Related MCP server: Postgres Scout MCP

仕組み

• カタログ (registry.yaml) — 非秘密のルーティング。customers → environments → services として構成され、各サービスはデータベース名と secret_ref（ボールトへのポインタ。決して認証情報そのものではない）にマッピングされます。

• ボールト (vault.enc) — scrypt から導出されたキーを使用した AES-256-GCM。データベース認証情報を保持し、起動時にパスフレーズを使用してメモリ内に一度だけ復号化されます。

• トンネルプール — sshtunnel を介した (customer, environment) ごとの SSH トンネル。一時的な 127.0.0.1 ポートにバインドされます。

• エグゼキュータ — psycopg。run_query は Postgres の READ ONLY トランザクションで実行されます（エンジンは書き込みを拒否します）。run_write_query は confirm=true を必要とします。

インストール

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

設定

設定は環境変数から取得されます。デフォルトはプロジェクトルートからの相対パスで解決されます。

プロビジョニング（初回セットアップ）

1. テンプレートをコピーして実際の値を入力します:

   cp bootstrap.example.yaml bootstrap.yaml

2. SSH 秘密鍵を keys/ に配置します（ファイル名はカタログの pem_key フィールドと一致する必要があります）。

3. 非秘密のカタログと暗号化されたボールトを生成します（サーバー実行時に再利用するパスフレーズを求められます）:

   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 は 平文 の認証情報を保持します。これは git で無視されます。ボールトが存在するようになったら、削除するかオフラインで保管してください。

コマンドラインツール

（コンソールコマンドは pip install -e . 後に存在します。python -m db_mcp_server.<module> 形式は常に機能します。）

アシスタントに公開されるツール

• list_databases() — カタログ（customers → environments → services）。秘密情報は含まれません。

• run_query(customer, environment, service, sql, max_rows?) — 読み取り専用。

• run_write_query(customer, environment, service, sql, confirm) — ゲート付き書き込み。

ドメイン障害は例外ではなく構造化された {error_code, message} として返されるため、アシスタントは対応できます。

MCP クライアントへの登録

.mcp.json の例（パスを調整してください）。${DB_MCP_PASSPHRASE} を使用して、パスフレーズをファイルに書き込む代わりにシェルから読み取ります:

{
  "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}"
      }
    }
  }
}

セキュリティに関する注意

• vault.enc、keys/、bootstrap.yaml、*.env、*.pem は git で無視されます。決してコミットしないでください。

• ボールトのパスフレーズは DB_MCP_PASSPHRASE（またはプロンプト）を介して提供されます。registry.yaml、argv、ログには決して保存されません。

• db-vault は DB パスワードを非表示プロンプト（getpass）で読み取ります。argv では読み取りません。

• run_query は Postgres エンジンレベルで読み取り専用です。書き込みには confirm=true が必要です。

テスト

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

DB 統合テストは、DB_MCP_TEST_DSN が到達可能な PostgreSQL を指している場合にのみ実行されます。

ロードマップ（このビルドには含まれません）

永続的な監査証跡、マルチユーザー操作、外部シークレットマネージャーのバックエンド、スキーマイントロスペクションツール、および認証情報の分離をハードバウンダリにするための権限拒否リスト。