MochiuWiki : SUSE, EC, PCB

MCPサーバ - DBHub

概要

DBHub (bytebase/dbhub) は、Model Context Protocol (MCP) を通じてAIアシスタントがデータベースと対話するための標準化されたインターフェースを提供するサーバである。
Bytebaseが開発しており、MITライセンスの下でTypeScriptで実装されている。

MCPとは、AIアシスタントが外部ツールやデータソースと通信するためのオープンプロトコルであり、DBHubはAIとデータベースをシームレスに統合する役割を担う。

対応するデータベースは、PostgreSQL、MySQL、MariaDB、SQL Server、SQLiteである。
Claude Desktop、Claude Code、OpenCode、Cursor、VS Code等の主要なMCPクライアント環境で動作する。

主な特徴は以下の通りである。

  • ゼロ依存の設計で、Node.jsの npx またはDockerで即座に実行可能
  • トークン効率的な設計により、AIとのやり取りを最適化
  • execute_sql と search_objects の2つの組み込みMCPツールを提供
  • SSHトンネリングによるリモートデータベースへのセキュアなアクセスに対応
  • SSL/TLS接続に対応
  • 読み取り専用モードによるデータ保護が可能
  • TOML設定ファイルによるカスタムツールの定義が可能
  • Windows、MacOS、Linuxの主要なOSで動作



DBHubの機能

DBHubは、SQLクエリ実行とスキーマ探索の2つの組み込みMCPツールに加え、カスタムツールの定義機能を提供する。

execute_sql

execute_sql は、SQLクエリを実行するためのツールである。
セミコロン区切りで複数のSQLステートメントを1度に実行することも可能である。

execute_sql ツールのパラメータ
パラメータ 型 説明
sql 文字列 実行するSQLクエリ
セミコロン区切りで複数ステートメントの実行も可能
source 文字列 TOML設定ファイルで定義したデータベース接続のソースID


search_objects

search_objects は、データベースのスキーマ情報を探索するためのツールである。
テーブル、カラム、インデックス等のデータベースオブジェクトを検索・一覧表示することができる。

search_objects ツールのパラメータ
パラメータ 型 説明
object_type 文字列 (必須) 検索対象
指定可能な値は、schema、table、column、procedure、index
pattern 文字列 SQL LIKE構文でのフィルタパターン
デフォルト: %
schema 文字列 フィルタリングするスキーマ名
detail_level 文字列 詳細度レベル
指定可能な値は、names、summary、full
limit 数値 最大結果数
デフォルト: 100
最大: 1000


カスタムツール

dbhub.toml設定ファイル を使用することにより、パラメータ付きのSQLテンプレートをカスタムツールとして定義できる。
これにより、繰り返し使用するクエリをMCPツールとして登録し、AIアシスタントから呼び出すことが可能になる。

カスタムツールの設定例を以下に示す。

 [[tools]]
 name = "search_users"
 source = "mydb"
 description = "Search for users by name or email"
 statement = "SELECT id, name, email FROM users WHERE name LIKE {{pattern}} LIMIT {{limit}}"
 
 [[tools.parameters]]
 name = "pattern"
 type = "string"
 description = "Search pattern (use % for wildcard)"
 required = true
 
 [[tools.parameters]]
 name = "limit"
 type = "integer"
 description = "Maximum number of results"
 required = false
 default = 100



動作要件

共通の要件

OS問わず共通して必要な要件を以下に示す。

  • Node.js環境 (npxコマンドの実行に必要) または Docker
    npxを使用する場合は、Node.js LTS版のインストールが必要
  • 対応するデータベースサーバへのネットワークアクセス
    ローカルまたはリモートのデータベースサーバに接続可能な環境が必要


対応データベース

DBHubが対応するデータベースとDSN形式を以下に示す。

対応データベースとDSN形式
データベース DSN形式 デフォルトポート
PostgreSQL postgres://user:password@host:port/dbname?sslmode=disable 5432
MySQL mysql://user:password@host:port/dbname 3306
MariaDB mysql://user:password@host:port/dbname 3306
SQL Server sqlserver://user:password@host:port;database=dbname 1433
SQLite sqlite:///path/to/database.db -



インストール

npxによる実行

npx コマンドを使用することにより、インストール不要で直接DBHubを実行できる。

PostgreSQLへの接続例を以下に示す。

npx @bytebase/dbhub@latest --dsn "postgres://<ユーザ名>:<パスワード>@<ホスト名 または IPアドレス  例: localhost>:5432/mydb?sslmode=disable"


Dockerによる実行

Dockerコンテナを使用してDBHubを実行することも可能である。

Dockerコンテナからホストマシンのデータベースにアクセスするには、localhost の代わりに host.docker.internal を使用する。

docker run --rm --init --name dbhub                       \
                       --publish 8080:8080 bytebase/dbhub \
                       --transport http                   \
                       --port 8080                        \
                       --dsn "postgres://<ユーザ名>:<パスワード>@host.docker.internal:5432/mydb?sslmode=disable"


デモモード

--demo オプションを使用することで、サンプルの従業員データベースを自動起動してDBHubの機能を試すことができる。

npx @bytebase/dbhub@latest --demo



設定

設定ファイルの場所

各MCPクライアントの設定ファイルの場所は以下の通りである。

Claude Desktopの設定ファイルを以下に示す。

  • Linux
    ~/.config/Claude/claude_desktop_config.json
  • MacOS
    ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows
    %APPDATA%\Claude\claude_desktop_config.json


Claude Codeの設定ファイルを以下に示す。

  • Linux
    ~/.config/claude/settings.json
  • MacOS
    ~/Library/Application Support/claude/settings.json
  • Windows
    %APPDATA%\claude\settings.json


OpenCodeの設定ファイルを以下に示す。

  • Linux / MacOS / Windows (共通)
    $HOME/.opencode.json


Claude Desktopでの設定

Claude Desktopの設定ファイルに以下の内容を追記する。

 {
   "mcpServers": {
     "dbhub": {
       "command": "npx",
       "args": [
         "-y",
         "@bytebase/dbhub@latest",
         "--transport",
         "stdio",
         "--dsn",
         "postgres://user:password@localhost:5432/mydb?sslmode=disable"
       ]
     }
   }
 }


設定ファイルを保存した後、Claude Desktopを再起動して設定を反映する。

Claude Codeでの設定

Claude Codeでは、claude mcp add コマンドを使用してMCPサーバを追加できる。

claude mcp add dbhub -- npx -y @bytebase/dbhub@latest \
                     --transport stdio                \
                     --dsn "postgres://<ユーザ名>:<パスワード>@localhost:5432/mydb?sslmode=disable"


設定ファイルを使用する場合は、以下の内容を settings.jsonファイル に追記する。

 {
   "mcpServers": {
     "dbhub": {
       "command": "npx",
       "args": [
         "-y",
         "@bytebase/dbhub@latest",
         "--transport",
         "stdio",
         "--dsn",
         "postgres://user:password@localhost:5432/mydb?sslmode=disable"
       ]
     }
   }
 }


OpenCodeでの設定

OpenCodeの設定ファイル (~/.opencode.jsonファイル) に以下の内容を追記する。

 {
   "mcpServers": {
     "dbhub": {
       "type": "stdio",
       "command": "npx",
       "args": [
         "-y",
         "@bytebase/dbhub@latest",
         "--transport",
         "stdio",
         "--dsn",
         "postgres://user:password@localhost:5432/mydb?sslmode=disable"
       ]
     }
   }
 }


コマンドラインオプション

下表に、DBHubで使用可能なコマンドラインオプションの一覧を示す。

コマンドラインオプション一覧
オプション 説明
--transport 通信プロトコル
stdio または http を指定する

デフォルト: stdio
--port HTTPサーバのポート番号 (httpトランスポート使用時)

デフォルト: 8080
--dsn データベース接続文字列
--config TOML設定ファイルのパス

デフォルト: ./dbhub.toml
--id インスタンスID (複数インスタンス実行時の識別子)

デフォルト: default
--demo デモモードの有効化 (サンプルデータベースを自動起動)
--ssh-host SSHトンネル先ホスト名
--ssh-user SSHユーザ名
--ssh-key SSHキーファイルパス

デフォルト: ~/.ssh/id_rsa
--ssh-passphrase SSHキーのパスフレーズ
--ssh-proxy-jump SSHプロキシジャンプ設定 (踏み台経由接続)


--config を使用する場合、--dsn と --id オプションの同時指定はできない。

dbhub.toml設定ファイル

TOML形式の設定ファイルを使用することで、複数のデータベース接続やカスタムツールを定義できる。

  • 単一データベースに対する基本的な設定例 (読み取り専用) 
     [[sources]]
 id = "mydb"
 dsn = "postgres://user:password@localhost:5432/mydb"
 
 [[tools]]
 name = "execute_sql"
 source = "mydb"
 readonly = true
 max_rows = 1000
 
 [[tools]]
 name = "search_objects"
 source = "mydb"

  • 複数データベースを使用する場合の設定例 
     [[sources]]
 id = "postgres_db"
 dsn = "postgres://user:password@db.example.com:5432/production"
 connection_timeout = 30
 query_timeout = 60
 sslmode = "require"
 
 [[sources]]
 id = "mysql_db"
 dsn = "mysql://user:password@analytics.example.com:3306/analytics"
 
 [[tools]]
 name = "execute_sql"
 source = "postgres_db"
 readonly = true
 max_rows = 5000
 
 [[tools]]
 name = "search_objects"
 source = "mysql_db"


SSHトンネリング

SSHトンネリングを使用することで、踏み台サーバ経由でリモートデータベースにセキュアに接続できる。

  • コマンドラインでのSSH接続設定例 
     npx @bytebase/dbhub@latest --transport stdio \
    --dsn "postgres://user:password@localhost:5432/mydb" \
    --ssh-host "jump.example.com" \
    --ssh-user "sshuser" \
    --ssh-key "/home/user/.ssh/id_rsa"

  • TOML設定ファイルでSSHトンネリングを設定する場合 
     [[sources]]
 id = "remote_db"
 dsn = "postgres://user:password@localhost:5432/mydb"
 ssh_host = "jump.example.com"
 ssh_user = "sshuser"
 ssh_key = "/home/user/.ssh/id_rsa"



使用方法

DBHubの各ツールは、AIアシスタントが自然言語の指示を受けて自動的に呼び出す。

SQLクエリの実行例

SQLクエリの実行に関する操作例を以下に示す。

  • データベースのテーブル一覧を取得する場合 
     # プロンプト例 :
 
 データベース内のテーブル一覧を表示してください。

  • 特定のテーブルからデータを取得する場合 
     # プロンプト例 :
 
 usersテーブルの全データを取得してください。

  • 条件を指定してクエリを実行する場合 
     # プロンプト例 :
 
 ordersテーブルからステータスが「completed」のレコードを取得してください。


スキーマ探索の例

スキーマ情報の取得に関する操作例を以下に示す。

  • テーブル構造を確認する場合 
     # プロンプト例 :
 
 usersテーブルのカラム定義を教えてください。

  • データベース内のテーブルを検索する場合 
     # プロンプト例 :
 
 名前に「user」を含むテーブルを検索してください。



トラブルシューティング

共通の問題

OS問わず発生する可能性がある問題と対処法を以下に示す。

共通トラブルシューティング
問題 対処法
npxコマンドが動作しない Node.js LTS版がインストールされているか確認する。
npm cache clean --force を実行してキャッシュをクリアする。
データベース接続エラー DSN文字列が正しいか確認する。
データベースサーバが起動しているか確認する。
ファイアウォール設定を確認する。
ポート競合 (httpトランスポート使用時) --port オプションで別のポート番号を指定する。
使用中のポートを lsof -i :8080 等で確認する。
SSHトンネリングの接続エラー SSHキーのパスと権限を確認する。
SSHホストへのアクセスが可能か確認する。
Permission deniedエラー データベースユーザの権限を確認する。
SSHキーファイルの権限 (600) を確認する。



「https://mochiu.net/index.php?title=MCPサーバ_-_DBHub&oldid=14428」から取得