はじめに

Claude Codeは、MCPサーバーを通じて外部システムと連携することで、その機能を大幅に拡張できます。中でもデータベースとの連携は、開発者の日常業務を効率化する強力な機能です。DBHub MCPサーバーを使えば、自然言語でSQLクエリを生成・実行し、スキーマを分析し、マイグレーションの作成を支援してもらうことが可能になります。

本記事では、DBHub MCPサーバーのセットアップから実践的な活用方法までを詳しく解説します。この記事を読むことで、以下のことができるようになります。

  • DBHub MCPサーバーをClaude Codeに設定する
  • 自然言語でデータベースをクエリする
  • スキーマ分析と設計提案をClaude Codeに依頼する
  • マイグレーションファイルの作成を効率化する

実行環境

  • オペレーティングシステム: macOS 10.15以上、Ubuntu 20.04以上/Debian 10以上、Windows 10以上（WSL 1/2またはGit for Windows）
  • ハードウェア: 4GB以上のRAM
  • Node.js 18以上（npmインストールの場合のみ必要）
  • インターネット接続（認証およびAI処理に必要）
  • シェル環境: Bash、Zsh、またはFish推奨

前提条件

  • コマンドライン操作の基礎知識
  • Gitの基本操作（clone、commit、push等）
  • プログラミングの基礎知識（言語は問わない）
  • Claude.aiまたはAnthropic Consoleアカウント
  • Claude Codeのインストールと認証が完了していること
  • MCPの基本概念を理解していること（Claude CodeとMCP連携入門を参照）

DBHub MCPサーバーとは

DBHubは、Bytebase社が開発したゼロ依存・トークン効率に優れたデータベース用MCPサーバーです。Claude Code、Claude Desktop、Cursor、VS Codeなど、MCP対応クライアントからデータベースに接続し、自然言語で操作できるようになります。

graph LR
    A[Claude Code] --> B[DBHub<br>MCPサーバー]
    B --> C[PostgreSQL]
    B --> D[MySQL]
    B --> E[SQLite]
    B --> F[SQL Server]
    B --> G[MariaDB]

DBHubの特徴

DBHubには以下の特徴があります。

特徴 説明
ゼロ依存 外部パッケージに依存せず軽量
トークン効率 2つのMCPツールに集約し、コンテキストウィンドウを最大化
マルチデータベース対応 PostgreSQL、MySQL、MariaDB、SQL Server、SQLite
マルチ接続 TOML設定で複数データベースに同時接続
ガードレール 読み取り専用モード、行数制限、クエリタイムアウト
セキュア接続 SSHトンネル、SSL/TLS暗号化対応

提供されるMCPツール

DBHubは以下のMCPツールを提供します。

execute_sql

SQLクエリを実行するツールです。SELECT、INSERT、UPDATE、DELETEなどの操作、トランザクション制御、DDL操作が可能です。読み取り専用モードや行数制限などの安全機能も備えています。

search_objects

データベースオブジェクト（スキーマ、テーブル、カラム、インデックス、プロシージャ）を検索・一覧表示するツールです。パターンマッチングと段階的な詳細表示により、トークン使用量を最小化しながらスキーマを探索できます。

DBHub MCPサーバーのセットアップ

基本的なインストールと接続

Claude CodeにDBHubを追加する最もシンプルな方法は、claude mcp addコマンドを使用することです。

PostgreSQLへの接続

1
2
3

claude mcp add --transport stdio dbhub -- npx @bytebase/dbhub@latest \
  --transport stdio \
  --dsn "postgres://user:password@localhost:5432/dbname"

MySQLへの接続

1
2
3

claude mcp add --transport stdio dbhub -- npx @bytebase/dbhub@latest \
  --transport stdio \
  --dsn "mysql://user:password@localhost:3306/dbname"

SQLiteへの接続

1
2
3

claude mcp add --transport stdio dbhub -- npx @bytebase/dbhub@latest \
  --transport stdio \
  --dsn "sqlite:///./data/local.db"

Dockerを使用したインストール

Dockerを使用する場合は、HTTPトランスポートでDBHubを起動します。

1
2
3
4
5
6
7

docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  bytebase/dbhub \
  --transport http \
  --port 8080 \
  --dsn "postgres://user:password@host.docker.internal:5432/dbname"

Docker内からホストマシンのデータベースに接続する場合は、localhostではなくhost.docker.internalを使用してください。

その後、Claude CodeにHTTPトランスポートで追加します。

1

claude mcp add --transport http dbhub http://localhost:8080/mcp

Windowsでの設定

Windows環境（WSL以外）では、cmd /cラッパーが必要です。

1
2
3

claude mcp add --transport stdio dbhub -- cmd /c npx @bytebase/dbhub@latest ^
  --transport stdio ^
  --dsn "postgres://user:password@localhost:5432/dbname"

デモモードでの動作確認

DBHubの機能を試すには、組み込みのデモモードを使用します。

1
2
3

claude mcp add --transport stdio dbhub-demo -- npx @bytebase/dbhub@latest \
  --transport stdio \
  --demo

デモモードでは、サンプルの従業員データベース（SQLite）が自動的に作成され、すぐにDBHubの機能を体験できます。

接続確認

DBHubが正しく設定されているか確認するには、Claude Code内で/mcpコマンドを実行します。

1
2
3
4
5

> /mcp

利用可能なMCPサーバー:
  dbhub (stdio) - 接続済み
    ツール: execute_sql, search_objects

自然言語によるSQLクエリ生成

DBHub MCPサーバーを設定すると、Claude Codeに自然言語でデータベース操作を依頼できるようになります。

基本的なクエリの実行

1

> 今月登録したユーザーの一覧を表示して

Claude Codeは以下のような流れで処理します。

  1. search_objectsでテーブル構造を確認
  2. 適切なSQLクエリを生成
  3. execute_sqlでクエリを実行
  4. 結果を整形して表示

生成されるSQLの例は以下の通りです。

1
2
3
4

SELECT id, name, email, created_at
FROM users
WHERE created_at >= DATE_TRUNC('month', CURRENT_DATE)
ORDER BY created_at DESC;

集計クエリの生成

1

> カテゴリ別の商品売上を集計して、売上の多い順に表示して

Claude Codeは複雑な集計クエリも自動生成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

SELECT
    c.name AS category_name,
    COUNT(o.id) AS order_count,
    SUM(oi.quantity * oi.price) AS total_revenue,
    AVG(oi.quantity * oi.price) AS avg_order_value
FROM categories c
JOIN products p ON c.id = p.category_id
JOIN order_items oi ON p.id = oi.product_id
JOIN orders o ON oi.order_id = o.id
WHERE o.status = 'completed'
GROUP BY c.id, c.name
ORDER BY total_revenue DESC;

条件付きクエリの実行

1

> 過去90日間購入がない顧客で、以前は月1回以上購入していた人を見つけて

Claude Codeはビジネスロジックを理解し、適切なSQLを生成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

WITH customer_purchase_history AS (
    SELECT
        c.id,
        c.email,
        MAX(o.created_at) AS last_purchase,
        COUNT(o.id) AS total_orders,
        COUNT(o.id) / GREATEST(
            EXTRACT(MONTH FROM AGE(MAX(o.created_at), MIN(o.created_at))),
            1
        ) AS monthly_avg
    FROM customers c
    JOIN orders o ON c.id = o.customer_id
    WHERE o.status = 'completed'
    GROUP BY c.id, c.email
)
SELECT id, email, last_purchase, total_orders, monthly_avg
FROM customer_purchase_history
WHERE last_purchase < CURRENT_DATE - INTERVAL '90 days'
  AND monthly_avg >= 1
ORDER BY last_purchase;

スキーマ分析と設計提案

DBHubのsearch_objectsツールを使うと、Claude Codeにデータベーススキーマを詳細に分析させることができます。

スキーマの全体像を把握する

1

> このデータベースのテーブル構成を説明して

Claude Codeはsearch_objectsを使用して段階的にスキーマを探索します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[search_objects実行]
object_type: "schema"
detail_level: "summary"

[search_objects実行]
object_type: "table"
detail_level: "names"

データベース構成:
- public スキーマ
  - users (ユーザー管理)
  - products (商品マスタ)
  - orders (注文)
  - order_items (注文明細)
  - categories (商品カテゴリ)
  - reviews (商品レビュー)

テーブル設計のレビュー

1

> ordersテーブルの設計をレビューして、改善点があれば提案して

Claude Codeはスキーマを分析し、設計上の問題点を指摘します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

ordersテーブルの分析結果:

現在の構造:
- id: SERIAL PRIMARY KEY
- customer_id: INTEGER (FK)
- status: VARCHAR(50)
- total_amount: DECIMAL(10,2)
- created_at: TIMESTAMP
- updated_at: TIMESTAMP

改善提案:

1. ステータスカラムの正規化
   現在VARCHAR(50)ですが、ENUM型またはステータスマスタテーブルへの
   外部キー参照を推奨します。これにより不正な値の登録を防止できます。

2. インデックスの追加
   customer_idにインデックスがありません。顧客別の注文検索が
   頻繁に行われる場合、パフォーマンス低下の原因になります。

   CREATE INDEX idx_orders_customer_id ON orders(customer_id);

3. 論理削除の検討
   deleted_atカラムの追加を検討してください。注文履歴は
   コンプライアンス上、物理削除より論理削除が適切な場合があります。

正規化の分析

1

> このデータベースの正規化状態を分析して、非正規化されている部分があれば指摘して

Claude Codeは複数のテーブル間の関係を分析し、正規化の問題を特定します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

正規化分析結果:

問題1: productsテーブルのcategory_name冗長性
- category_idとcategory_nameの両方が存在
- category_nameはcategoriesテーブルから取得すべき
- 更新時の不整合リスクあり

推奨アクション:
ALTER TABLE products DROP COLUMN category_name;

問題2: order_itemsテーブルの非正規化
- product_nameとunit_priceを保持（意図的な履歴保持の可能性）
- 商品マスタ変更の影響を受けないメリットがある
- ビジネス要件次第では許容範囲

マイグレーション作成支援

Claude Codeは、データベースの変更に必要なマイグレーションファイルの作成も支援します。

新規テーブルのマイグレーション

1

> 商品在庫を管理するinventoryテーブルのマイグレーションを作成して

Claude Codeは、既存のスキーマを分析した上で、整合性のあるマイグレーションを生成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

-- Migration: create_inventory_table
-- Created at: 2026-01-08

-- Up Migration
CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    product_id INTEGER NOT NULL REFERENCES products(id) ON DELETE CASCADE,
    warehouse_id INTEGER NOT NULL,
    quantity INTEGER NOT NULL DEFAULT 0,
    reserved_quantity INTEGER NOT NULL DEFAULT 0,
    reorder_point INTEGER NOT NULL DEFAULT 10,
    last_restocked_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT positive_quantity CHECK (quantity >= 0),
    CONSTRAINT positive_reserved CHECK (reserved_quantity >= 0),
    CONSTRAINT reserved_not_exceed_quantity CHECK (reserved_quantity <= quantity)
);

CREATE INDEX idx_inventory_product_id ON inventory(product_id);
CREATE INDEX idx_inventory_warehouse_id ON inventory(warehouse_id);
CREATE UNIQUE INDEX idx_inventory_product_warehouse 
    ON inventory(product_id, warehouse_id);

-- Down Migration
DROP TABLE IF EXISTS inventory;

カラム追加のマイグレーション

1

> usersテーブルに2要素認証用のカラムを追加するマイグレーションを作成して

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

-- Migration: add_2fa_columns_to_users
-- Created at: 2026-01-08

-- Up Migration
ALTER TABLE users
    ADD COLUMN two_factor_enabled BOOLEAN NOT NULL DEFAULT FALSE,
    ADD COLUMN two_factor_secret VARCHAR(255),
    ADD COLUMN two_factor_backup_codes TEXT[],
    ADD COLUMN two_factor_confirmed_at TIMESTAMP;

-- Down Migration
ALTER TABLE users
    DROP COLUMN IF EXISTS two_factor_confirmed_at,
    DROP COLUMN IF EXISTS two_factor_backup_codes,
    DROP COLUMN IF EXISTS two_factor_secret,
    DROP COLUMN IF EXISTS two_factor_enabled;

インデックス最適化のマイグレーション

1

> 現在のクエリパフォーマンスを分析して、必要なインデックスのマイグレーションを提案して

Claude Codeはテーブル構造と想定されるクエリパターンを分析します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

-- Migration: add_performance_indexes
-- Created at: 2026-01-08
-- Based on query pattern analysis

-- Up Migration

-- ordersテーブル: 日付範囲とステータスでの検索最適化
CREATE INDEX idx_orders_created_status 
    ON orders(created_at DESC, status);

-- order_itemsテーブル: 商品別売上集計の最適化
CREATE INDEX idx_order_items_product_order 
    ON order_items(product_id, order_id);

-- reviewsテーブル: 商品別レビュー取得の最適化
CREATE INDEX idx_reviews_product_created 
    ON reviews(product_id, created_at DESC);

-- Down Migration
DROP INDEX IF EXISTS idx_reviews_product_created;
DROP INDEX IF EXISTS idx_order_items_product_order;
DROP INDEX IF EXISTS idx_orders_created_status;

複数データベースの同時接続

本番環境、ステージング環境、開発環境など、複数のデータベースを同時に管理する場合は、TOML設定ファイルを使用します。

TOML設定ファイルの作成

プロジェクトルートにdbhub.tomlファイルを作成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# 本番データベース（読み取り専用）
[[sources]]
id = "production"
dsn = "postgres://readonly:password@prod.db.example.com:5432/myapp"
connection_timeout = 60
query_timeout = 30
sslmode = "require"

[[tools]]
name = "execute_sql"
source = "production"
readonly = true
max_rows = 1000

[[tools]]
name = "search_objects"
source = "production"

# ステージングデータベース
[[sources]]
id = "staging"
dsn = "postgres://admin:password@staging.db.example.com:5432/myapp"
connection_timeout = 30
query_timeout = 15

[[tools]]
name = "execute_sql"
source = "staging"
readonly = false
max_rows = 5000

[[tools]]
name = "search_objects"
source = "staging"

# ローカル開発データベース
[[sources]]
id = "local"
dsn = "postgres://postgres:postgres@localhost:5432/myapp_dev"

[[tools]]
name = "execute_sql"
source = "local"
readonly = false

[[tools]]
name = "search_objects"
source = "local"

TOML設定でDBHubを起動

1
2
3
4

# TOML設定を使用してDBHubを追加
claude mcp add --transport stdio dbhub -- npx @bytebase/dbhub@latest \
  --transport stdio \
  --config ./dbhub.toml

環境を指定したクエリ実行

複数データベースが設定されている場合、Claude Codeに環境を指定して操作を依頼できます。

1

> 本番環境のordersテーブルから今日の注文数を取得して

Claude Codeはproductionソースを使用してクエリを実行します。

1

> ステージング環境で、新しいユーザー登録処理をテストして

Claude Codeはstagingソースを使用し、書き込み操作も実行できます。

カスタムツールの定義

よく使うクエリをカスタムツールとして定義すると、パラメータ検証付きで安全に再利用できます。

カスタムツールの設定例

dbhub.tomlにカスタムツールを追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

[[sources]]
id = "production"
dsn = "postgres://readonly:password@prod.db.example.com:5432/myapp"

# ユーザー検索カスタムツール
[[tools]]
name = "search_users_by_email"
description = "メールアドレスのパターンでユーザーを検索する"
source = "production"
statement = """
    SELECT id, name, email, created_at, last_login_at
    FROM users
    WHERE email ILIKE '%' || $1 || '%'
    ORDER BY created_at DESC
    LIMIT $2
"""

[[tools.parameters]]
name = "email_pattern"
type = "string"
description = "検索するメールアドレスのパターン"

[[tools.parameters]]
name = "limit"
type = "integer"
description = "取得する最大件数"
default = 10

# 売上レポートカスタムツール
[[tools]]
name = "get_sales_report"
description = "指定期間の売上レポートを取得する"
source = "production"
statement = """
    SELECT
        DATE(o.created_at) AS order_date,
        COUNT(DISTINCT o.id) AS order_count,
        COUNT(DISTINCT o.customer_id) AS unique_customers,
        SUM(o.total_amount) AS total_revenue
    FROM orders o
    WHERE o.created_at BETWEEN $1 AND $2
      AND o.status = $3
    GROUP BY DATE(o.created_at)
    ORDER BY order_date DESC
"""

[[tools.parameters]]
name = "start_date"
type = "string"
description = "開始日（YYYY-MM-DD形式）"

[[tools.parameters]]
name = "end_date"
type = "string"
description = "終了日（YYYY-MM-DD形式）"

[[tools.parameters]]
name = "status"
type = "string"
description = "注文ステータス"
allowed_values = ["pending", "completed", "cancelled", "refunded"]

カスタムツールの使用

カスタムツールを定義すると、Claude Codeから直接呼び出せます。

1

> example.comドメインのユーザーを20件検索して

Claude Codeはsearch_users_by_emailカスタムツールを使用し、パラメータ検証を行った上でクエリを実行します。

セキュリティのベストプラクティス

データベースをAIツールに接続する際は、セキュリティに十分注意が必要です。

読み取り専用アカウントの使用

本番データベースに接続する場合は、必ず読み取り専用のデータベースアカウントを使用してください。

1
2
3
4
5
6
7

-- PostgreSQLでの読み取り専用ロール作成例
CREATE ROLE readonly_user WITH LOGIN PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE myapp TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
    GRANT SELECT ON TABLES TO readonly_user;

DBHubの読み取り専用モード設定

1
2
3
4
5

[[tools]]
name = "execute_sql"
source = "production"
readonly = true  # 書き込み操作を禁止
max_rows = 1000  # 結果行数を制限

SSHトンネルの使用

本番データベースへの接続にはSSHトンネルを使用することを推奨します。

1
2
3
4
5
6
7
8
9

[[sources]]
id = "production"
dsn = "postgres://user:pass@database.internal:5432/mydb"

# SSHトンネル設定
ssh_host = "bastion.example.com"
ssh_port = 22
ssh_user = "deploy"
ssh_key = "~/.ssh/production_key"

機密情報の取り扱い

DSN内のパスワードなどの機密情報は、環境変数で管理することを推奨します。

1
2
3
4
5
6
7

# 環境変数でDSNを設定
export DATABASE_URL="postgres://user:password@localhost:5432/dbname"

# DBHubの起動時に環境変数を使用
claude mcp add --transport stdio dbhub -- npx @bytebase/dbhub@latest \
  --transport stdio \
  --dsn "$DATABASE_URL"

トラブルシューティング

接続エラーの対処

接続エラーが発生した場合は、以下を確認してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[エラー] Connection refused

原因:
- データベースサーバーが起動していない
- ホスト名またはポート番号が間違っている
- ファイアウォールで接続がブロックされている

対処:
1. データベースサーバーの起動確認
2. DSN内のホスト名とポート番号を確認
3. ネットワーク接続を確認

認証エラーの対処

1
2
3
4
5
6
7
8
9

[エラー] Authentication failed

原因:
- ユーザー名またはパスワードが間違っている
- ユーザーにデータベースへの接続権限がない

対処:
1. DSN内の認証情報を確認
2. データベースユーザーの権限を確認

DBHubが表示されない場合

Claude Code内で/mcpを実行してもDBHubが表示されない場合は以下を確認します。

1
2
3
4
5
6
7
8

# MCPサーバー一覧を確認
claude mcp list

# DBHubを再追加
claude mcp remove dbhub
claude mcp add --transport stdio dbhub -- npx @bytebase/dbhub@latest \
  --transport stdio \
  --dsn "your-connection-string"

まとめ

本記事では、DBHub MCPサーバーを使用してClaude Codeからデータベースを操作する方法を解説しました。

  • DBHub MCPサーバーのセットアップ方法と複数の接続オプション
  • 自然言語によるSQLクエリ生成と実行
  • スキーマ分析と設計改善の提案依頼
  • マイグレーションファイルの作成支援
  • 複数データベースの同時接続とカスタムツールの定義
  • セキュリティのベストプラクティス

DBHub MCPサーバーを活用することで、データベース操作の効率が大幅に向上します。特に、スキーマの理解が必要な場面や、複雑なSQLクエリの作成、マイグレーションの設計において、Claude Codeの支援は非常に有効です。

まずはデモモードで機能を試し、実際のプロジェクトで活用してみてください。

参考リンク