MCP Toolbox for DatabasesをClaude Codeにつなぐ手順 — 複数DBを1つで操作

MCP Toolbox for Databasesは、Google側のリポジトリが公開しているオープンソースのMCPサーバーです。PostgreSQLやMySQL、BigQuery、Spannerなど複数のDBを、Claude CodeのようなMCPクライアントにまとめて渡せます。DBごとに別のMCPサーバーを探して入れ直す必要はありません。

接続の形は2つあります。1つはDB名を指定するだけで動く「prebuilt」、もう1つは tools.yaml に接続先とクエリを書く「カスタムツール」です。複数のDBを1つのMCPサーバーで扱いたいときは、後者が向いています。

MCP Toolbox for Databasesとは何か

MCP Toolbox for Databasesは、AIエージェントやIDEをDBへ直接つなぐオープンソースのMCPサーバーです。READMEは用途を2つに分けています。

• ビルド時の利用: Claude CodeやGemini CLIなどから、汎用のprebuiltツールでDBへ話しかける
• 実行時の利用: 本番のエージェント向けに、構造化クエリを持つ専用ツールを tools.yaml で定義する

名前の経緯にも触れておきます。以前は「Gen AI Toolbox for Databases」で、リポジトリ名は genai-toolbox でした。現在のリポジトリ名は mcp-toolbox に変わっています。古い記事やブログで genai-toolbox と書かれていても、同じものです。

3つの接続方式はどう使い分けるか

Claude Codeからの入口は3通りです。選び方は「何個のDBを、誰が使うか」で決まります。

3行目が、このページの主題です。理由は次の節で説明します。

手順1: prebuiltでDB 1個をつなぐ

最短の入口は、プロジェクトルートの .mcp.json にprebuiltを書く方法です。公式のPostgreSQL向けガイドが示す形に沿うと、次のようになります。

{
  "mcpServers": {
    "postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt", "postgres", "--stdio"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "app_dev",
        "POSTGRES_USER": "readonly_agent",
        "POSTGRES_PASSWORD": "${PG_PASSWORD}"
      }
    }
  }
}

toolbox バイナリは、リリースページのバージョンを指定して curl で取得し、実行権限を付けます。macOS(Apple Silicon)なら次のとおりです。

export VERSION=1.15.0
curl -L -o toolbox \
  https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox
chmod +x toolbox
./toolbox --version

バイナリを置きたくない場合は、README記載のnpm経由でも起動できます。command を npx、args を ["-y", "@toolbox-sdk/server", "--prebuilt=postgres", "--stdio"] にします。ただしREADMEは、この方法を「性能より手軽さを優先したもの」と位置づけています。常用するならバイナリかコンテナです。

Claude Codeは .mcp.json の env や args で ${VAR} 形式の環境変数展開を使えます。パスワードを直書きせずに済むので、.mcp.json をチームでコミットする場合は展開を使います。

起動後に使えるツールは、PostgreSQLの場合 list_tables と execute_sql の2つです。テーブルと説明の一覧を返すツールと、任意のSQLを実行するツールです。

手順2: tools.yamlで複数DBを1つのMCPにまとめる

prebuiltは、PostgreSQLにもMySQLにも list_tables と execute_sql という同じ名前のツールが付きます。2つのprebuiltを並べて起動することは公式のCLIドキュメントで認められていますが、記載されている例はalloydb-postgresとalloydb-postgres-adminの組み合わせです。同名のツールが並んだときの扱いは、公式ドキュメントに記載がありません。

そこで、複数DBを1つにまとめるなら tools.yaml を使います。sources で接続先を、tools で操作を、それぞれ名前付きで定義します。

kind: source
name: app-pg
type: postgres
host: 127.0.0.1
port: 5432
database: app_dev
user: ${PG_USER}
password: ${PG_PASSWORD}
---
kind: source
name: legacy-mysql
type: mysql
host: 127.0.0.1
port: 3306
database: legacy
user: ${MYSQL_USER}
password: ${MYSQL_PASSWORD}
---
kind: tool
name: search_orders_pg
type: postgres-sql
source: app-pg
description: 新DBから注文を顧客IDで検索する。
parameters:
  - name: customer_id
    type: integer
    description: 顧客ID。
statement: SELECT * FROM orders WHERE customer_id = $1 LIMIT 50;
---
kind: tool
name: search_orders_legacy
type: mysql-sql
source: legacy-mysql
description: 旧DBから注文を顧客IDで検索する。
parameters:
  - name: customer_id
    type: integer
    description: 顧客ID。
statement: SELECT * FROM orders WHERE customer_id = ? LIMIT 50;

ポイントは、ツール名にDBの区別を埋めていることです。search_orders_pg と search_orders_legacy なら、Claudeが「どちらのDBを引くか」を名前から選べます。description もモデルが読む手がかりなので、DBの違いを一言入れておきます。

kind: toolset を足すと、ツールを用途別にまとめて読み込めます。たとえば analyst_set に検索系だけを入れ、更新系は別のセットに置く使い方です。

サーバーを起動してClaude Codeに登録する

HTTPで常駐させる場合は、--config に tools.yaml を渡して起動します。既定の待受は 127.0.0.1:5000 です。

./toolbox --config tools.yaml

別のターミナルで、Claude Codeに登録します。Streamable HTTPのエンドポイントは /mcp です。

claude mcp add --transport http toolbox http://127.0.0.1:5000/mcp
claude mcp get toolbox

特定のツールセットだけを渡したいときは、URLを http://127.0.0.1:5000/mcp/{toolset_name} にします。DBごとに権限の違うチームなら、セット単位で接続先を変えられます。

常駐させたくなければ、stdioでも同じ tools.yaml を使えます。./toolbox --stdio と --config を組み合わせ、.mcp.json の command と args に書きます。stdioではログの水準が既定で warn になり、debug と info は出せません。起動に失敗したときの手がかりが少ないので、最初の切り分けはHTTP起動のほうが楽です。

動作確認とよくあるつまずき

接続できたかは、Claude Code内で /mcp を開いて行を確認します。コマンドなら claude mcp get toolbox で状態を見られます。.mcp.json に書いたサーバーは、初回に承認を求められます。⏸ Pending approval と出たら、claude を対話で起動して承認します。

次の2点も、公式ドキュメントに根拠のある注意点です。

• バージョンの下限: MCPで接続できるのはToolbox 0.3.0以降です
• 変更の追随: Toolboxは tools.yaml を既定で動的に再読み込みします。止めたいときは --disable-reload を付けます

本番DBに向けるときの権限の絞り方

ここが一番大事な節です。公式のprebuilt設定ページは、prebuiltを「信頼できる開発者を手伝うビルド時」の用途と明記し、信頼できない相手と話す実行時には安全性が足りないと警告しています。

同じページは、execute_sql のようにSQLを丸ごと渡せるツールについて、ツール注釈やMCPクライアント側の確認は便利なガードではあっても、DBのセキュリティ境界ではないと述べています。対策として挙がっているのは次の3つです。

1. エージェント専用のDBユーザーを作る
2. 探索用途なら、読ませたいスキーマ・テーブル・ビューに限った SELECT 権限だけを渡す
3. 決まった作業には、パラメータ付きのカスタムツールを使う

手順2の tools.yaml は、3つ目をそのまま実装した形です。ClaudeにSQLを書かせず、固定のSQLに引数だけを渡させています。

readOnlyでDBエンジン側に鍵を掛ける

公式にはread-onlyの専用ページがあります。ソース定義に readOnly: true を足すと、エンジン側で書き込みを拒否する構成にできます。ページの例はCloud SQL for PostgreSQLのソースですが、書き方はソースの定義に1行足すだけです。

prebuiltでは環境変数で切り替えます。ページの表によると、Cloud SQL(PostgreSQL)は CLOUD_SQL_POSTGRES_READONLY=true、AlloyDBは ALLOYDB_POSTGRES_READONLY=true、BigQueryは BIGQUERY_READONLY=true です。この表に載っているのはCloud SQL、AlloyDB、BigQueryで、手順1のようなPostgreSQL(自前ホスト)やMySQL向けの項目は載っていません。そのため、自前ホストのDBでは次の層、つまりDBユーザーの権限で守ります。

Claude Code側の許可設定を重ねる

Claude Code側では、MCPツールの許可を mcp__<サーバー名>__<ツール名> の形で書けます。mcp__toolbox__* のように、サーバー名の後にワイルドカードを置く書き方もあります。読み取り系だけを自動許可し、書き込み系は毎回確認に回す設定を、.claude/settings.json に置いた例です。

{
  "permissions": {
    "allow": ["mcp__toolbox__search_orders_pg", "mcp__toolbox__search_orders_legacy"],
    "ask": ["mcp__postgres__execute_sql"]
  }
}

サーバー名は claude mcp add や .mcp.json で付けた名前に合わせます。上の例なら、手順2のサーバーが toolbox、手順1のサーバーが postgres です。

ClaudeにDBの使い方を覚えさせる

接続できても、どのDBに何があるかをClaudeは知りません。CLAUDE.md に短い規約を書いておくと、ツールの選び間違いが減ります。

## データベース
- 新しい注文は `search_orders_pg`、移行前の注文は `search_orders_legacy` で引く
- 1回の取得は50行まで。結果が多いときは条件を絞ってから再実行する
- `execute_sql` を使う前に `list_tables` でスキーマを確認する
- INSERT / UPDATE / DELETE は実行せず、SQLを提示して止まる

そのうえで、「顧客ID 1042の注文を両方のDBから引いて、金額が食い違う行を出して」のように頼みます。ツールが2つに分かれているので、Claudeは両方を呼び、結果を突き合わせます。差分の出力が想定と違うときは、そのSQLをこちらで読み直せます。

隣接するDB別の接続との違い

同じエンジンを個別に扱う記事もあります。BigQueryならBigQueryプラグインの導入記事、Cloud SQL for PostgreSQLならCloud SQLプラグインの記事、AlloyDBはAlloyDBプラグインの記事、SpannerはOAuthとIAMロールを軸にしたSpanner MCPサーバーの記事があります。

AlloyDBプラグインは、Toolboxの alloydb-postgres プリビルドサーバーをプラグインとして包んだものです。そこから言えるのは、1つのエンジンを少ない手数で入れたいならプラグイン、複数のエンジンをまとめたい、あるいはツールの中身を自分で決めたいならToolbox本体、という分け方になります。BigQuery、ClickHouse、DuckDBを比べたい場合は、3つのMCP接続の比較記事が判断材料になります。

まとめ

DBが1個で試すだけなら、prebuiltの --prebuilt=postgres --stdio で足ります。2個以上になったら tools.yaml に切り替え、ツール名にDBの区別を入れるのが、ClaudeにDBを選び間違えさせない近道です。

そして、どの形でも守りの本体はDB側です。専用ユーザーと SELECT 権限、使えるなら readOnly を先に決め、Claude Codeの許可設定は二重の保険として重ねます。prebuiltは1.0より前の扱いで、ツールがバージョン間で変わりうると公式ガイドにあります。バージョンを固定して使い、更新のたびにツール名を見直します。