database-mcp

SQLデータベースMCPサーバー。真のサーバーサイド結果ページングを備えています。これは、既存のデータベースMCPサーバーにはない機能です（DBHubは行数を制限し、GoogleのMCP Toolboxはすべてを返し、mcp-alchemyは4000文字で切り捨てます）。

PostgreSQLリファレンス実装。

なぜ

既存のSQL MCPサーバーはすべて、大きな結果を切り捨てるか、モデルのコンテキストに全体をダンプします。MCP仕様はリスト操作（tools/list）のみをページングし、ツール結果はページングしません。database-mcpはそのギャップを埋めます：

• クエリはPostgreSQLサーバーサイドカーソル（DECLARE/FETCH FORWARD）として保持トランザクション内で一度だけ実行されます。

• 各fetch(cursor)は、最後のページが終了した正確にその場所から続行します。再実行もOFFSET再スキャンもなく、MVCCスナップショットにより、同時書き込みが発生しても結果は安定しています。

• ページは行数（page_size）とレンダリングバイト数（max_page_bytes）の両方で制限されます。過大なセルは明示的なマーカーで切り捨てられます。

• 保持カーソルは制限されています：最大N個の同時実行（LRU退避）、TTLアイドル退避、さらにidle_in_transaction_session_timeoutをサーバーサイドのバックストップとして使用します。使い切ったカーソルは自動的に閉じられます。

Related MCP server: pgsql-mcp

接続プロファイル — 実行時にAIが管理

接続は名前付きプロファイルで、~/.config/database-mcp/profiles.json（chmod 600）に永続化されます。AIはツールを介して、サーバーを再起動することなく、プロファイルを追加、変更、テスト、削除できます：

• profile_add(name, dsn, allow_writes=false, description, make_default, test=true)

• profile_remove(name) · profile_test(name) · profiles()

• すべてのクエリツールはオプションのprofileパラメータを受け取ります。省略時はデフォルトプロファイルが使用されます。

プロファイルはデフォルトで読み取り専用です（セッションレベルのdefault_transaction_read_only）。書き込みには明示的なallow_writes=trueプロファイルが必要です。

SSHブリッジ

プロファイルは、SSH経由でのみアクセス可能なデータベース（典型的な「Postgresがリモートホストのlocalhostでリッスンしている」設定）に到達できます：

profile_add(name="prod", dsn="postgresql://app@dbhost:5432/app",
            ssh_host="dbhost")

• トンネルはシステムsshサブプロセス（-N -L、BatchMode、キープアライブ）です。~/.ssh/config、キー、エージェントはそのまま適用されます。認証は非対話的に機能する必要があります。

• ssh_remote_host/ssh_remote_portは、SSHホストから見たDSNのホスト/ポートをデフォルトとします。DSNホストがSSHホストと等しい場合、127.0.0.1（通常のケース）をデフォルトとします。

• トンネルは遅延起動し、使用のたびにヘルスチェックされ、自動的に再構築されます。ページング中にトンネルが死んだ場合、そのカーソルは明確なエラーで無効化され、次のクエリで再接続されます。

• 多重化（ControlMaster）はトンネル接続では明示的に無効化され、トンネルの寿命がサブプロセスの寿命と正確に一致するようにします。

ツール

結果はコンパクトなJSONです — 列は一度だけ、行は配列として — 他のサーバーが出力する行辞書形式の約半分のトークンです。queryはestimated_rows（EXPLAINによるプランナー推定値）も返すため、モデルは何をページングしているかを把握できます。

インストールと実行

uv pip install -e .
database-mcp --dsn postgresql://user@host:5432/db      # registers profile "default"
database-mcp                                           # start empty, add profiles at runtime

Claude Code登録：

claude mcp add database -- database-mcp --dsn postgresql://user@host:5432/db

オプション：--profiles FILE、--allow-writes、--page-size 50、 --max-page-size 500、--max-page-bytes 32000、--max-cell 400、 --cursor-ttl 300、--max-cursors 4、--statement-timeout 30、 --keepalive 120、--connect-timeout 5。 環境変数：DATABASE_MCP_DSN / DATABASE_URL、DATABASE_MCP_PROFILES。

古さの処理

死んだ接続は、ハングする代わりに各レイヤーで迅速に検出されます：

• SSHトンネル：ServerAliveInterval = --keepalive（デフォルト2分）でServerAliveCountMax=1 — 1回のプローブ失敗でトンネルプロセスが終了し、エンジンマネージャーが次の使用時に検出して遅延再構築します。

• DB接続：TCPキープアライブ（keepalives_idle = --keepalive、10秒ごとのプローブ、3回の失敗）で、約30秒で死んだピアを検出します — プール外の固定カーソル接続も含みます。

• プールチェックアウトチェック：配布されるすべての接続は、安価なラウンドトリップで検証されます。古いものは破棄され、透過的に置き換えられます — 呼び出し元はエラーを見ることはありません。アイドル状態のプール接続は--keepalive秒後に再利用され、接続試行は--connect-timeout（デフォルト5秒）後に失敗します（TCPデフォルトの約2分ではなく）。

テスト

uv pip install -e '.[dev]'
pytest            # needs a local PostgreSQL (DBMCP_TEST_DSN to override)

ライセンス

MIT