Berth -- データベースMCPサーバー

License: MIT

データの安全な停泊地 -- AIツール向けのデータベースアクセス。

Berthは、AIアシスタントにPostgreSQL、SQLite、MySQLデータベースへの安全で構造化されたアクセスを提供するModel Context Protocolサーバーです。スキーマの検査、クエリの実行、データの管理、マイグレーションの生成、バックアップの実行を行うための13個のツールを提供します。これらはすべて、偶発的な損傷を防ぐ3段階の安全モデルによって管理されています。

安全モデル

Berthは、許可されるSQLを制御する3つの動作モードを強制します：

モード	デフォルト	許可される操作	ブロックされる操作
read-only	はい	`SELECT`, `EXPLAIN`	すべての書き込み
write	いいえ	`INSERT`, `UPDATE`, `DELETE`, `CREATE`	`DROP`, `TRUNCATE`, `ALTER DROP`, `WHERE`句のない`DELETE`
admin	いいえ	すべて	破壊的な操作には確認トークンが必要（60秒で期限切れ）

サーバーはread-onlyモードで起動します。writeモードおよびadminモードは明示的に有効にする必要があります。adminモードでの破壊的な操作は、60秒後に期限切れとなるワンタイム確認トークンを生成します。AIは意図を確認するためにトークンをエコーバックする必要があります。

ツール

ツール	説明	主要なパラメータ
`health`	サーバーのヘルスチェック	--
`db_connect`	データベースへの接続	`dsn` (接続文字列)
`db_query`	SELECTクエリの実行 (自動的にLIMIT 1000を追加)	`connection_id`, `sql`
`db_execute`	INSERT/UPDATE/DELETEの実行 (安全モードを尊重)	`connection_id`, `sql`, `confirmation_token`
`db_schema`	テーブル、ビュー、インデックスの一覧表示	`connection_id`
`db_describe`	テーブルの列詳細	`connection_id`, `table`
`db_relationships`	外部キー関係	`connection_id`, `table` (任意)
`db_size`	データベースおよびテーブルのサイズ	`connection_id`
`db_active_queries`	現在実行中のクエリ (PostgreSQLのみ)	`connection_id`
`db_explain`	クエリに対するEXPLAIN ANALYZEの実行	`connection_id`, `sql`
`generate_migration`	スキーマ比較によるマイグレーションSQLの生成	`connection_id` + `target_sql`, または `from_connection` + `to_connection`
`db_backup`	データベースバックアップの作成	`connection_id`, `output_path`
`db_restore`	バックアップからの復元 (adminモード + 確認トークン)	`connection_id`, `input_path`, `confirmation_token`

スキーママイグレーション

generate_migrationツールは2つのスキーマを比較し、一方から他方へ移行するためのダイアレクト対応SQLを生成します。2つの動作モードがあります：

モード1 — ライブデータベース vs ターゲットDDL:

connection_id（アクティブな接続）とtarget_sql（目的のスキーマを記述したCREATE TABLE文）を提供します。Berthはライブデータベースをイントロスペクションし、解析されたターゲットとの差分を抽出します。

モード2 — 2つのライブデータベース:

from_connectionとto_connection（2つのアクティブな接続ID）を提供します。Berthは両方をイントロスペクションし、ソースをターゲットに変換するためのマイグレーションを生成します。

生成される内容:

新しいテーブルに対するCREATE TABLE
新しい列に対するALTER TABLE ADD COLUMN
型、NULL許容性、デフォルト値の変更に対するALTER TABLE ALTER COLUMN / MODIFY COLUMN
インデックスの変更に対するCREATE INDEX / DROP INDEX
外部キーの変更に対するADD CONSTRAINT / DROP CONSTRAINT
DROP TABLEおよびDROP COLUMNは警告付きでコメントアウトされます（安全第一）

ダイアレクトの処理:

PostgreSQL -- ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULTを使用
MySQL -- すべての列変更にMODIFY COLUMN、DROP INDEX ... ON tableを使用
SQLite -- サポートされていない操作について警告し、それが必要な変更（ALTER COLUMN、古いバージョンでのDROP COLUMN、制約の変更）に対してテーブル再構築パターンを含めます

サポートされているデータベース

PostgreSQL -- pg_stat_activity, EXPLAIN ANALYZE, pg_dump/psqlバックアップ/復元を含む完全サポート
SQLite -- PRAGMAイントロスペクション、sqlite3 CLI経由の.backup/.restoreを含む完全サポート
MySQL -- information_schemaイントロスペクション、mysqldump/mysqlバックアップ/復元を含む完全サポート

インストール

PyPIから:

pip install berth-mcp

または分離された環境で:

pipx install berth-mcp

MySQLサポートにはオプションの依存関係が必要です:

pip install berth-mcp[mysql]

PostgreSQL (asyncpg) および SQLite (aiosqlite) ドライバーはデフォルトで含まれています。

使用方法

サーバーの実行:

berth

BerthはMCPプロトコルを使用してstdio経由で通信します。スタンドアロンで実行するのではなく、MCPクライアントによって起動されるように設計されています。

Claude Code

claude mcp add berth -- berth

Claude Desktop

claude_desktop_config.jsonに追加します:

{
  "mcpServers": {
    "berth": {
      "command": "berth",
      "args": []
    }
  }
}

仮想環境にインストールされている場合は、フルパスを使用してください:

{
  "mcpServers": {
    "berth": {
      "command": "/path/to/venv/bin/berth",
      "args": []
    }
  }
}

環境変数

変数	デフォルト	説明
`BERTH_BACKUP_DIR`	現在の作業ディレクトリ	バックアップおよび復元パス用のサンドボックスディレクトリ。すべてのパスはこのディレクトリ内に留まるよう検証されます。

セキュリティ

3段階の安全モデル -- デフォルトで読み取り専用、書き込みには明示的なオプトインが必要、破壊的な操作には確認トークンが必要
確認トークン -- DROP, TRUNCATE, ALTER DROP, およびテーブル全体のDELETEに対して、60秒で期限切れとなるワンタイムUUIDを使用
SQLインジェクション保護 -- PRAGMA文で使用する前にテーブル名をsqlite_masterに対して検証。全体を通してパラメータ化されたクエリを使用
パストラバーサル保護 -- バックアップ/復元パスは解決され、BERTH_BACKUP_DIR内に留まるよう検証。NULLバイトは拒否
パスワードマスキング -- DSNパスワードは、すべての表示出力およびエラーメッセージでマスクされます

開発

git clone https://github.com/seayniclabs/berth.git
cd berth
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
python -m pytest tests/ -q

PostgreSQLおよびMySQLの統合テストにはDockerが必要です:

docker compose -f tests/docker-compose.test.yml up -d
python -m pytest tests/ -q
docker compose -f tests/docker-compose.test.yml down

ライセンス

MIT

Berth