MCP Toolbox for Databases — インストール & ライブデモ

なぜ使うのか

主な機能

1バイナリ・多エンジン対応：Postgres、MySQL、BigQuery、Spanner、AlloyDB、Cloud SQL、SQLite、MSSQL、Redis、Couchbase、Dgraph、Neo4j
宣言的なtools.yaml — 各ツールは名前付き・パラメータ化されたSQL文であり、自由形式のSQLハッチではない
ゼロ設定で即使用できるプリビルト設定（--prebuilt postgres）
接続プーリングと認証（IAM、OAuth、APIキー）をプロンプト外で一元管理
Stdio・HTTP/SSEトランスポート対応 — Claude Desktop、Cursor、Codex、IDE、カスタムエージェントで動作
ツールレベルの認可ルール — 破壊的な操作の呼び出し権限を制限可能

ライブデモ

実際の動作

mcp-toolbox-databases.replay ▶ 準備完了

0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方： MCP Toolbox for Databases

本番Postgresへの安全な読み取り専用アクセスをClaudeに付与する方法

👤 データ流出リスクなしにLLM分析を行いたいバックエンド／データエンジニア ⏱ ~25 min intermediate

使うタイミング： execute_sql ツールで DROP TABLE を実行させることなく、Claudeに実際のデータベースへ質問させたい場合。

前提条件

libpq URLでアクセス可能なPostgres — 読み取り専用ロールを使用し、アプリの書き込みユーザーは絶対に使わないこと
DockerまたはGoのインストール — Toolboxは単一バイナリで配布；Dockerイメージが最も簡単

フロー

プリビルトPostgresプロファイルでToolboxを起動

Start mcp-toolbox in stdio mode using --prebuilt postgres and POSTGRES_URL pointing at the read replica.✓ コピーしました

→ Toolboxが tools registered: list_tables, describe_table, execute_sql_readonly をログ出力する
Claude Desktopへ組み込む

Add the toolbox docker config to claude_desktop_config.json under mcpServers, then restart Claude.✓ コピーしました

→ /mcp でtoolboxのツールが一覧表示される — エラーなし
実際の質問をする

Toolbox: list tables. Then for orders, what's the median order value in the last 7 days? Show me the exact SQL you ran.✓ コピーしました

→ ClaudeがlistTables → describe_table → execute_sql_readonly をSELECT文で呼び出す（UPDATE/DELETEは絶対に実行しない）

結果： 更新リスクゼロで実データの読み取り専用分析が可能。全クエリの監査ログも残る。

注意点

書き込みユーザーを指定した場合、Claudeがいずれ更新系ツールを呼び出す — GRANT SELECT のみのロールを常に使用。psqlの \du で確認
並列エージェント呼び出しで接続プールが枯渇する — tools.yamlで pool.max_open_conns を設定；デフォルトは保守的な値

組み合わせ： filesystem · github

パラメータバリデーション付きのアナリストツールを手書きで定義する

👤 生のSQLではなく、認可済みクエリのみを使いたいチーム ⏱ ~20 min intermediate

使うタイミング： 「今月のトップ10顧客」をClaudeに答えさせたいが、独自のJOINを組み立てさせたくない場合。

前提条件

tools.yamlファイル — ~/.mcp-toolbox/tools.yaml に作成

フロー

パラメータ化されたツールを記述

Add a tool top_customers to tools.yaml: parameter since: date, statement SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ コピーしました

→ Toolboxがリロードし、top_customers のみを公開（execute_sql_readonlyなし）
Claudeから呼び出す

Use top_customers since=2026-04-01 and explain the result.✓ コピーしました

→ バリデート済みの日付パラメータによる単一ツール呼び出しと整形された結果

結果： ロックダウンされたアナリスト向けインターフェース — 宣言していないものはClaudeが実行できない。

注意点

プリビルトのexecute_sqlツールを削除し忘れる — --prebuilt を外し、自分のtools.yamlのみを読み込む

SQLを書かずにBigQueryデータセットを探索する

👤 Google Cloudのアナリスト ⏱ ~20 min intermediate

使うタイミング： BigQueryプロジェクトがあり、コスト制御をしながらClaudeに横断的に質問させたい場合。

前提条件

GCPプロジェクト＋データセット — gcloud auth application-default login を実行してToolboxが認証情報を拾えるようにする

フロー

--prebuilt bigqueryでToolboxを起動

Run toolbox --prebuilt bigquery with PROJECT=my-proj.✓ コピーしました

→ ツール bq_list_datasets、bq_dry_run、bq_query が登録される
必ずドライランを先に実行

Before running any query, call bq_dry_run to estimate the bytes scanned. If > 1GB, ask me before running.✓ コピーしました

→ 課金クエリの前にコスト見積もりが表示される

結果： コスト制御付きのBigQuery回答 — 予想外の高額クエリなし。

注意点

デフォルトロケーションの不一致（USとEU） — BIGQUERY_LOCATION 環境変数を設定する

1つのClaudeセッションから複数のデータベースを横断クエリする

👤 クロスストアの問題をデバッグするエンジニア ⏱ ~30 min advanced

使うタイミング： 注文データはPostgres、イベントはBigQuery、キャッシュはRedisにある — 3つすべてを横断して相関分析が必要な場合。

前提条件

複数ソースを持つtools.yaml — sources: 以下に各ソースを定義し、ツールにソースをタグ付けする

フロー

3つのソースをすべて接続

Add postgres-prod, bq-events, redis-cache as sources in tools.yaml. Add 1–2 tools per source.✓ コピーしました

→ Toolboxが起動し、すべてのソースがhealthyとマークされる
クロスストアの質問をする

For order 12345: pull the row from Postgres, the event timeline from BigQuery, and the current cache state from Redis. Reconcile.✓ コピーしました

→ 3つのツール呼び出しがファンアウトし、1つの一貫した回答が得られる

結果： 3つの別々のツールやSSHセッションなしにクロスストアデバッグが可能。

注意点

ソースのヘルスチェックが静かに失敗する — 起動前に toolbox validate tools.yaml を実行する

組み合わせ： filesystem

組み合わせ

他のMCPと組み合わせて10倍の力を

mcp-toolbox-databases + filesystem

クエリ結果を取得してワークスペースのCSVとして保存する

Toolbox: top 100 orders this week. Filesystem: save as /tmp/orders.csv.✓ コピーしました

mcp-toolbox-databases + github

ClaudeがスキーマChange案を提案した後にSQLマイグレーションのPRを作成する

Toolbox: describe the orders table. GitHub: open a PR adding an index on customer_id.✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
list_tables	schema?: str	最初の探索ステップ	1 query
describe_table	table: str	未知のテーブルに対してSQLを書く前	1 query
execute_sql_readonly	sql: str	読み取りレプリカでの自由形式の分析	1 query
bq_dry_run	sql: str	BigQuery：bq_queryの前に必ず実行	free (dry run)
bq_query	sql: str	ドライランで許容コストが確認された後	billable per bytes scanned
<your-custom-tool>	depends on tools.yaml	tools.yamlで宣言したもの全般	1 query

コストと制限

運用コスト

APIクォータ: なし — DBの接続上限に依存
呼び出しあたりのトークン: 結果サイズに応じて100〜5000
金額: OSS無料；利用するDB／クラウドは通常通り課金
ヒント: tools.yamlでの結果行数を制限（例：LIMIT 200）；BigQueryは必ずbq_dry_runを経由する

セキュリティ

権限、シークレット、影響範囲

最小スコープ： read-only DB role

認証情報の保管： 環境変数またはGoogle ADC；Toolboxは認証情報を永続化しない

データ送信先： 直接DB接続 — サードパーティを経由しない。Toolboxはローカル専用。

絶対に付与しない： DBA DROP/TRUNCATE on prod

本番環境は必ず読み取りレプリカ＋読み取り専用ロールで保護すること；アプリの書き込みユーザーは使用禁止

トラブルシューティング

よくあるエラーと対処法

connection refused / pool exhausted

tools.yamlでpool.max_open_connsを増やす；DBの接続上限を確認

確認： psql, run SELECT count(*) FROM pg_stat_activity

tool not found

--prebuilt 使用時、ツール名は例えば pg_list_tables；toolbox list-tools で確認

BigQuery 403 access denied

gcloud auth application-default login を実行し roles/bigquery.dataViewer を付与

確認： bq ls

Spanner Cloud SDK errors

GOOGLE_APPLICATION_CREDENTIALSをサービスアカウントのJSONに設定

代替案

MCP Toolbox for Databases 他との比較

代替案	代わりに使う場面	トレードオフ
DBHub	Postgres/MySQL/SQL Serverをカバーする依存ゼロの単一バイナリが欲しい場合	BigQuery/Spannerの深みが少なく、Google IAMなし
Postgres MCP (modelcontextprotocol)	Postgres専用でYAML設定不要	制限が少ない — デフォルトでexecute_sqlを公開
MySQL MCP (benborla)	MySQL専用・読み取り専用	単一エンジン・よりシンプル

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る