Claude Media
Claude CodeでMCPからデータベースに接続する方法 — 読み取り専用から始める安全設計
MCPチュートリアル

Claude CodeでMCPからデータベースに接続する方法 — 読み取り専用から始める安全設計

Claude CodeからMCPで社内データベースに接続する手順をまとめます。読み取り専用ユーザーとpermissionsルールで書き込みを止める設計を軸に、プラグインとclaude mcp addの使い分けまで扱います。

読了目安 約13分

Claude CodeはMCP(Model Context Protocol)経由で社内データベースに直接つながります。PostgreSQLやMySQLのスキーマを読み、集計クエリを自然文で投げられます。問題は逆方向です。同じ接続経路でINSERTやDELETEも通せてしまうため、最初の設計を誤ると本番データを壊すエージェントになりかねません。実在するMCPサーバーDBHub(@bytebase/dbhub)を例に、読み取り専用から始めてどこまで許可を広げるかを手順で確認します。

MCPでデータベースに接続するとできること

MCPは、AIエージェントとツール・データソースをつなぐオープンな標準プロトコルです。プロトコル自体の仕組みはMCPとは — AIと外部ツールをつなぐ標準プロトコルに譲り、ここではデータベース接続の文脈に絞ります。

Claude Code公式ドキュメントは「PostgreSQLデータベースを使い、機能ENG-4521を使ったユーザー10人のメールアドレスを探して」という例を挙げています。テーブル名やJOIN条件を覚えなくても、スキーマを読ませて自然文で聞けば済みます。集計・異常値の発見・スキーマ探索が主な用途で、書き込みが必要な場面は限られます。

接続前に決めること — 読み取り専用ユーザーとDSNの用意

手順に入る前に、データベース側で2つ準備します。

  1. 読み取り専用のDBユーザーを作る。本番の管理者権限アカウントを接続文字列にそのまま書かない
  2. 接続文字列(DSN)をpostgres://user:password@host:port/dbnameの形で用意する。パスワードはgitに残さない前提で扱う

Claude Code公式ドキュメントの実例も、この前提で書かれています。

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

readonlyというユーザー名は説明用の例ですが、狙いは明確です。接続に使うDB権限そのものを読み取り専用に絞ることが、後述するMCP側の許可ルールより先に効く1段目のガードレールになります。

手順1: DBHubプラグインで最短接続する

DBHubはPostgreSQL・MySQL・MariaDB・SQL Server・SQLiteに対応するオープンソースのMCPサーバーです。Claude Code向けにはプラグイン形式の導入が最も速く、しかも既定で読み取り専用です。

/plugin marketplace add bytebase/dbhub
/plugin install dbhub@dbhub

インストール時にDSNの入力を求められますが、この値は設定ファイルに書かれず、Claude Codeのセキュアストレージに保存されます。プラグインはexecute_sqlにreadonly = trueとmax_rows = 1000をあらかじめ設定し、データベースエンジン側の読み取り専用モードも合わせて効かせる構成です。加えて/dbhub:setupが接続文字列づくりとトラブルシュートを担当します。/dbhub:exploreはスキーマ探索(名前一覧 → 概要 → 詳細の3段階)をトークン効率よく進めるスキルです。

1台のDBに読み取り専用でつなぐだけなら、この経路で設定ファイルは1つも要りません。

手順2: claude mcp addでTOML設定を直接登録する

複数DBへの同時接続、SSHトンネル経由の接続、書き込みが必要な運用系ツールなど、プラグインの既定を超える場合はclaude mcp addでTOML設定を直接登録します。

claude mcp add dbhub -- npx -y @bytebase/dbhub@latest \
  --transport stdio --config /path/to/dbhub.toml

TOML側では、データソースとツールごとの許可を個別に書けます。次の例は本番DBに対してexecute_sqlを読み取り専用・最大100行に絞り、スキーマ探索用のsearch_objectsだけを別途有効にしたものです。

[[sources]]
id = "production"
dsn = "postgres://readonly:pass@prod.db.com:5432/analytics"
 
[[tools]]
name = "execute_sql"
source = "production"
readonly = true
max_rows = 100
 
[[tools]]
name = "search_objects"
source = "production"

readonly = trueは、SQL文をキーワード分類器で判定する層と、データベース自身の読み取り専用モードの両方で強制されます。1つの設定項目が2つの独立した仕組みで裏打ちされている点が、単純な文字列フィルタより信頼できる理由です。

execute_sql自体を渡さずsearch_objectsだけを公開すれば、書き込みツールを提示すらしない、さらに保守的な構成も組めます。

[[sources]]
id = "production"
dsn = "postgres://readonly:pass@prod.db.com:5432/analytics"
 
[[tools]]
name = "search_objects"
source = "production"

DSNを設定ファイルに直書きしたくない場合は、環境変数の展開が使えます。.mcp.jsonはチームで共有する前提のファイルなので、パスワードは${DB_URL}のような変数参照にして、実値は各自の環境変数や.envファイル側に置きます。

本番DBが踏み台サーバーの先にしかない構成なら、DBHubはSSHトンネルにも対応します。--ssh-host・--ssh-user・--ssh-key(または--ssh-password)・--ssh-portをDSNと合わせて渡します。Claude Codeを動かすマシンから直接DBに到達できない環境でも、これで接続を張れます。踏み台を経由した多段の構成には--ssh-proxy-jumpも用意されています。

DBHubにはexecute_sql・search_objects以外にオプトインのツールが2つあります。explain_sqlはクエリを実際には実行せず実行計画だけを見せるツールで、複雑なクエリを投げる前の安全確認に向きます。health_checkはコネクションプールの状態とバッファキャッシュのヒット率を返し、接続まわりの異常検知に使えます。どちらもTOMLの[[tools]]に明示しない限り有効になりません。

登録後はclaude mcp listで状態を確認します。✔ Connectedならすぐ使えますが、✘ Failed to connectならDSNの誤りかネットワーク到達性を疑います。プロジェクトスコープの.mcp.json経由で追加した場合は⏸ Pending approvalと表示されることがあります。この状態では対話モードでclaudeを起動して承認するまでツールが使えません。

読み取り専用の設計を多重化する — DBの権限とMCPの許可ルール

DBユーザーの権限とMCPサーバー自身の設定は1段目・2段目の防御です。3段目として、Claude Code自体のpermissionsでMCPツール呼び出しを制御できます。ルールはmcp__<サーバー名>__<ツール名>という形式で書きます。

{
  "permissions": {
    "allow": ["mcp__db__search_objects"],
    "ask": ["mcp__db__execute_sql"]
  }
}

この設定なら、スキーマ確認はプロンプトなしで通り、クエリ実行のたびに確認を求められます。deny・ask・allowの優先順位はこの順で評価されます。mcp__db__execute_sqlをdenyに入れれば、TOML側の設定に関係なくClaude Codeの文脈からツールごと消えます。設計の詳細はClaude Code settings.json完全ガイドにまとめています。

接続に使うDB権限を読み取り専用にする1段目が最も効きます。MCPサーバー側のreadonly設定とClaude Codeの許可ルールは、設定ミスや将来の変更に備える保険として重ねる形です。監査ログが要る場合は、mcp__db__.*にマッチするPreToolUseフックで呼び出しを記録できます。

MCPデータベース連携の使い分け早見表

用途おすすめ度理由
1DBへの読み取り専用接続おすすめ度◎理由DBHubプラグインで設定ファイル不要、既定で読み取り専用
複数DBの同時接続おすすめ度◎理由TOMLの[[sources]]を複数書ける。プラグインは非対応
SSHトンネル経由の接続おすすめ度◯理由claude mcp add+TOMLで--ssh-host系オプションを使う
運用系の書き込み(INSERT等)おすすめ度△理由readonlyを外す判断は必要最小限の対象に限定してから
出所不明のDB系MCPサーバーおすすめ度✕理由接続前に提供元を確認する。プロンプトインジェクション経路になり得る

よくあるつまずき

  • プラグインと手動登録が二重に動く: プラグイン版とclaude mcp add版を両方入れると同じDBに2つのMCPサーバーが接続する。手動側を使うなら/pluginメニューでプラグインのMCPサーバーを無効化する
  • スキーマ出力が途中で切れる: MCPツールの出力は既定で25,000トークンが上限で、超えた分はディスクに退避されファイル参照に置き換わる。大きなスキーマを毎回全文読みたい場合はMAX_MCP_OUTPUT_TOKENS環境変数を引き上げる
  • DBに到達できない: Claude Codeを動かすマシンから直接データベースに接続する構成のため、VPNやネットワークの許可リストに入っていないと接続に失敗する。ローカル開発機と本番DBが別ネットワークにある場合は事前に疎通を確認する
  • --configと--dsnを同時に指定してしまう: DBHubはTOML設定と単一DSNのどちらか一方でしか起動しない。両方を渡すと設定エラーになるため、複数DBを扱いたくなった時点でDSN方式からTOML方式に切り替える
  • 大きなテーブルをsearch_objectsで一気に読む: 数百テーブル規模のスキーマは、名前一覧 → 概要 → 詳細と段階的に絞り込む使い方がトークンを節約する。DBHubの/dbhub:exploreスキルはこの手順を前提にしている

よくある質問

読み取り専用ユーザーを作らずにMCP側の設定だけで防げますか

MCP側のreadonly設定やClaude Codeのdenyルールは有効な保険ですが、接続に使うDBアカウントの権限そのものが緩ければ、設定ミス1つで書き込みが通ります。DB側の権限を絞ることを1段目にする設計が基本です。

DBHub以外のMCPデータベースサーバーもありますか

Anthropicが運営するAnthropic Directory(claude.ai/directory)には、DBHub以外にもレビュー済みのコネクターが並びます。本記事はClaude Code公式ドキュメントが実例として挙げているDBHubを軸に手順を確認しました。

プロジェクトスコープと個人スコープ、DB接続はどちらに向きますか

チームで同じ設定を共有したいなら.mcp.jsonのプロジェクトスコープ、自分だけの検証用途なら既定のローカルスコープが向きます。プロジェクトスコープにパスワードを直書きしないよう、環境変数展開を使う点は共通です。

書き込み権限が必要になったらどうすればよいですか

readonlyを外す対象は、必要なツール・必要なテーブルだけに限定します。全権限のDBユーザーをそのまま渡すのではなく、書き込みが要る操作専用のDBユーザーとMCPツール設定を別途用意するほうが、事故の範囲を狭く保てます。

まとめ

MCPでのデータベース接続は、DBHubのようなサーバーを使えば数分で動きます。肝心なのはつなぐ速さより、書き込みをどこで止めるかです。DBユーザーを読み取り専用にする、MCPサーバー側でreadonlyと行数上限を設定する、Claude Codeのpermissionsでツール呼び出し自体を制御する。3つを重ねておけば、どれか1つの設定ミスが本番データの事故に直結する事態を避けられます。まずはDBHubプラグインで1台のDBに読み取り専用でつなぎ、必要が出た段階でclaude mcp addとTOML設定に移行する順序が、遠回りに見えて実は安全です。

この記事を共有:XはてブLinkedIn

関連する記事

MCP をもっと見る →