dbridge-mcp

dbridge-mcp

AI エージェントが自然言語で SQL データベースを安全に、読み取り専用でクエリできるMCP サーバーです。

エージェントはスキーマを自動で検出し（list_tables、describe_table）、ユーザーの質問に応じて SELECT を作成して実行します。質問ごとに手書きのエンドポイントを用意する必要はありません。

SQLite、PostgreSQL、MySQL / MariaDB に対応しています。

特長

LLM はデータベースの中身を知ることができず、ウェブ検索ではプライベートデータにアクセスできません。dbridge は、そのデータへの保護された入口をモデルに提供します。データを読み取って回答できますが、書き込み、削除、テーブル全体の漏えいはできません。

dbridge がほかのデータベース MCP と異なる点は？

データベース MCP サーバーは数多くあります。dbridge は「安心して AI を実際のデータベースに接続できること」という考えを中心に設計されており、単一エンジンのサーバーにはない次の組み合わせを実現しています。

• 1 つのサーバーで 3 つのエンジンに対応。 SQLite、PostgreSQL、MySQL/MariaDB を、同じツールと同じ設定で利用できます。接続文字列を変更するだけで、ツールを変えずにデータベースを切り替えられます。
• 二重の読み取り専用保護。 SQL ガードが SELECT/WITH 以外を拒否し、さらにすべてのクエリをデータベースが強制する READ ONLY トランザクション内で実行します。そのため、ガードをすり抜けるクエリであっても書き込みはできません。
• 列単位のプライバシー保護。 列をモデルから完全に隠したり、クエリ可能な状態を保ったまま値をマスクしたりできます（a***@site.com）。多くのサーバーは、接続から参照できる情報をそのまま公開します。
• 被害範囲を抑える制御。 ユーザー指定の LIMIT に対する行数上限、クエリごとのタイムアウト、高コストなクエリを拒否する EXPLAIN ベースのコスト判定、1 分あたりのレート制限、上限付きの接続プールを備えています。
• ネイティブビルド不要。 SQLite では Node 組み込みの node:sqlite を使用するため、コンパイラーツールチェーンなしで npx -y dbridge-mcp を実行できます。
• クエリだけでなく、パフォーマンスも把握。 column_stats と index_health によって、実際のカーディナリティやインデックス使用状況のデータをモデルに提供します。また、test_index は hypopg でインデックスをシミュレートしてから構築できるため、モデルによる最適化の提案は推測ではなく、実際のデータベースに基づきます。

必要なのが「エージェントから SQL を実行すること」だけなら、対応するサーバーはたくさんあります。dbridge は、本当に大切なデータをエージェントに扱わせるためのサーバーです。

ツール

ツール	目的
list_tables	データベース内のすべてのテーブルを一覧表示します。
describe_table	テーブルのカラム、主キー、外部キー、行数の推定値を返します。
sample_table	テーブルの先頭行をプレビューします（json／csv／markdown）。
count_rows	テーブルの正確な行数を返します。
run_query	読み取り専用の SELECT／WITH を1つ実行し、行を json、csv、または markdown 形式で返します。
explain_query	クエリを実行せずに、実行計画と推定コストを返します。
column_stats	カラムごとの個別値の数とNULLの割合を返します。このカラムはインデックスを作成するのに十分な選択性がありますか？
index_health	インデックスをサイズとスキャン回数とともに一覧表示し、未使用、重複、無効なインデックスにフラグを付けます。
test_index	CREATE INDEX を作成せずにシミュレーションし、プランナーがそのインデックスを使用するかどうかを報告します（PostgreSQL、hypopg 経由）。
slow_queries	記録されたステートメントのうち、最もコストの高いものを呼び出し回数と実行時間とともに表示します（PostgreSQL の pg_stat_statements、MySQL の performance_schema）。
get_limits	適用中の安全制限（上限、タイムアウト、非表示／マスクされたカラム）を報告します。

リソース

リソース	目的
dbridge://schema	すべてのテーブルとそのカラムを含む完全なスキーマを、1つのJSONドキュメントとして返します。

プロンプト

プロンプト	目的
optimize	遅いクエリの検索、実行計画とインデックスの健全性の調査、提案する前に test_index ですべてのインデックス推奨を検証する、ガイド付きの最適化手順です。

要件

Node.js 22.5以降（SQLite は組み込みの node:sqlite を使用するため、ネイティブビルドの手順は不要です）。

インストール

公開済みパッケージには dbridge-mcp バイナリが含まれているため、使用する際にリポジトリのクローンやビルドは必要ありません。接続引数でデータベースを指定します。

npx -y dbridge-mcp demo.db                                  # SQLite (file path)
npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb"  # PostgreSQL
npx -y dbridge-mcp "mysql://user:pass@host:3306/mydb"       # MySQL / MariaDB

データベースエンジンは接続文字列から判別されます。ファイルパスはSQLite、postgres://／postgresql:// はPostgreSQL、mysql:// はMySQL／MariaDBです。

または、一度インストールしてグローバルに使用します。

npm install -g dbridge-mcp
dbridge-mcp "postgresql://user:pass@host:5432/mydb"

MCP クライアントはサーバーをサブプロセスとして起動します。詳しくは以下のクライアント別セクションをご覧ください。

Windows に関する注意： Windows では npx が .cmd スクリプトであるため、MCP クライアントから直接起動できません。cmd /c でラップし、"command": "cmd" を指定して、args に "/c", "npx", "-y", "dbridge-mcp", "<connection>" を設定してください。以下の例は直接実行する形式（macOS／Linux）です。Windows では cmd /c を先頭に追加してください。

Claude Desktop で使用する

Claude Desktop がサポートする設定はグローバル設定1つのみです。claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "dbridge": {
      "command": "npx",
      "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }
    }
  }
}

ローカルのSQLiteファイルを使用する場合は、接続文字列を .db ファイルの絶対パスに置き換えます。Claude Desktop を再起動し、「先月、最も売れた商品を5つ教えて」と尋ねてみてください。

Claude Code で使用する

CLI で現在のプロジェクトに追加します。

claude mcp add dbridge --scope project \
  -e DBRIDGE_CONFIG=/absolute/path/to/dbridge.config.json \
  -- npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb"

--scope project は共有可能な .mcp.json をプロジェクトルートに書き込みます。グローバルサーバーには --scope user を使用し、プロジェクトごとのプライベートなサーバーにする場合は省略します。.mcp.json は次のようになります。

{
  "mcpServers": {
    "dbridge": {
      "command": "npx",
      "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }
    }
  }
}

そのディレクトリから claude を実行し、プロジェクトサーバーを一度承認してから、/mcp で確認します。

Cursor で使用する

プロジェクトルートの .cursor/mcp.json（またはすべてのプロジェクトで使用する場合は ~/.cursor/mcp.json）に同じ mcpServers ブロックを追加し、Settings → MCP でサーバーを有効にしてから、Agent にデータに関する質問をします。

Windsurf で使用する

~/.codeium/windsurf/mcp_config.json に同じ mcpServers ブロックを追加し、Settings → Cascade → MCP でサーバーリストを更新します。

OpenCode で使用する

opencode.json（プロジェクトルートまたは ~/.config/opencode/opencode.json）に追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dbridge": {
      "type": "local",
      "command": ["npx", "-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "enabled": true
    }
  }
}

安全ガードを調整するには、environment ブロックを使ってサーバーに設定ファイルを指定します。

"environment": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }

Docker

イメージをビルドし、stdio 経由でサーバーを実行します。

docker build -t dbridge-mcp .
docker run --rm -i dbridge-mcp "postgresql://user:pass@host:5432/mydb"

設定ファイルをマウントし、DBRIDGE_CONFIG でそのファイルを指定します。

docker run --rm -i \
  -v "$PWD/dbridge.config.json:/config.json:ro" \
  -e DBRIDGE_CONFIG=/config.json \
  dbridge-mcp "postgresql://user:pass@host:5432/mydb"

安全性

• 接続は読み取り専用で開かれます。PostgreSQL と MySQL では、すべてのクエリが READ ONLY トランザクション内でも実行されるため、ガードをすり抜けたクエリがあっても、書き込みはデータベース自体によって拒否されます。
• SELECT と WITH ステートメントのみが許可されます。書き込み、DDL、データを変更する CTE は拒否されます。
• 呼び出しごとに実行できるステートメントは 1 つです。クエリでより大きな LIMIT が指定されていても、行数の上限が適用されます（デフォルトは 1000 行です）。
• PostgreSQL と MySQL の各クエリには、クエリごとのタイムアウト（statement_timeout／max_execution_time）が設定されているため、処理が終わらないクエリや高負荷なクエリがデータベースを占有することはありません。
• システムカタログと認証情報テーブル（information_schema、pg_authid、sqlite_master など）はクエリできません。スキーマの確認にはツールを使用します。
• 制限対象の列は完全に非表示にできます。モデルはスキーマ内でそれらの列を確認できず、クエリも実行できず、結果を受け取ることもありません。
• 許可リストまたはブロックリストを使ってテーブルを制限できます。ブロックされたテーブルは表示されず、クエリもできません。
• 列は非表示にする代わりにマスキングできます。列は表示されたままですが、値は一部が伏せられて返されます（例：a***@site.com）。
• EXPLAIN のコスト見積もりによって、高負荷なクエリを事前に拒否できます。また、呼び出し元に対して 1 分あたりのレート制限を設定できます。
• 接続プールのサイズには上限があるため、dbridge がデータベースの接続を使い果たすことはありません。

設定

各設定には、優先順位の低い順に3つの指定元があります。JSON ファイル（DBRIDGE_CONFIG）、環境変数、CLI フラグです。そのため、JSON ファイルを完全に省略し、必要な設定だけを指定できます。

npx -y dbridge-mcp "postgresql://user:pass@host/db" --max-rows 200 --statement-timeout-ms 3000 --masked-columns email,iban
DBRIDGE_MAX_ROWS=200 DBRIDGE_REQUIRE_SSL=true npx -y dbridge-mcp "postgresql://user:pass@host/db"

すべてを1か所にまとめることもできます。DBRIDGE_CONFIG に JSON ファイルを指定してください（完全なテンプレートについては dbridge.config.example.json を参照してください）。すべてのフィールドは省略可能です。

{
  "maxRows": 500,
  "hiddenColumns": ["ssn", "password_hash"],
  "maskedColumns": ["iban", { "column": "email", "strategy": "email" }],
  "allowedTables": ["products", "sales", "customers"],
  "blockedTables": ["employees", "audit_log"],
  "statementTimeoutMs": 5000,
  "maxCost": 100000,
  "rateLimitPerMin": 60,
  "maxPoolSize": 5,
  "connectionTimeoutMs": 10000,
  "requireSsl": true,
  "schemas": ["public", "reporting"],
  "auditLog": true
}

フィールド	CLI フラグ／環境変数	デフォルト	用途
maxRows	--max-rows / DBRIDGE_MAX_ROWS	1000	クエリごとに返される行数の上限です。より大きな LIMIT が指定されていても、この上限が適用されます。
hiddenColumns	--hidden-columns / DBRIDGE_HIDDEN_COLUMNS	[]	スキーマ、クエリ、結果から非表示にする列です。
maskedColumns	--masked-columns / DBRIDGE_MASKED_COLUMNS	[]	結果内の値をマスキングする列です（下記参照）。
maxCellChars	--max-cell-chars / DBRIDGE_MAX_CELL_CHARS	0	この文字数を超える文字列セルを切り詰めます。0 の場合は無効です。
maxResultBytes	--max-result-bytes / DBRIDGE_MAX_RESULT_BYTES	0	シリアライズ後の結果全体のサイズに上限を設定し、末尾の行を除外します。0 の場合は無効です。
allowedTables	--allowed-tables / DBRIDGE_ALLOWED_TABLES	[]	空でない場合、ここで指定したテーブルのみを公開します。
blockedTables	--blocked-tables / DBRIDGE_BLOCKED_TABLES	[]	常に非表示となり、クエリもできないテーブルです。
statementTimeoutMs	--statement-timeout-ms / DBRIDGE_STATEMENT_TIMEOUT_MS	10000	クエリごとのタイムアウトです（PostgreSQL の statement_timeout、MySQL の max_execution_time）。0 の場合は無効です。
maxCost	--max-cost / DBRIDGE_MAX_COST	0	EXPLAIN のコスト推定値がこの値を超えるクエリを拒否します（PostgreSQL／MySQL）。0 の場合は無効です。
rateLimitPerMin	--rate-limit-per-min / DBRIDGE_RATE_LIMIT_PER_MIN	0	1分あたりに実行できる、クエリを実行するツール呼び出しの最大数です。0 の場合は無効です。
maxPoolSize	--max-pool-size / DBRIDGE_MAX_POOL_SIZE	5	プール接続の最大数です（PostgreSQL／MySQL）。
connectionTimeoutMs	--connection-timeout-ms / DBRIDGE_CONNECTION_TIMEOUT_MS	10000	接続の確立を待つ時間です（PostgreSQL／MySQL）。
requireSsl	--require-ssl / DBRIDGE_REQUIRE_SSL	false	検証済み TLS 接続を必須にします（PostgreSQL／MySQL）。
schemas	--schemas / DBRIDGE_SCHEMAS	["public"]	PostgreSQL 専用です。公開するスキーマを指定します。複数のスキーマを指定すると、名前は schema.table 形式になります。
auditLog	--audit-log / DBRIDGE_AUDIT_LOG	false	すべてのツール呼び出し（クエリ、行数、所要時間、エラー）を JSON 形式で stderr に記録します。

コマンドラインまたは環境変数でリスト値を指定する場合は、カンマ区切りにします（--allowed-tables products,sales）。

エンジンに関する注意：statementTimeoutMs、maxCost、maxPoolSize、connectionTimeoutMs、requireSsl、schemas は、ネットワーク接続を使用するエンジン（PostgreSQL／MySQL）に適用されます。SQLite はローカルファイルなので、これらの設定を無視します。行数の上限、列／テーブルのアクセス制御、マスキングは、すべてのエンジンに適用されます。

列のマスキング

maskedColumns を使うと、列を表示したまま値をマスキングできます。各エントリには、列名（デフォルトで partial 戦略を使用）または { "column": ..., "strategy": ..., "keep": ... } 形式のオブジェクトを指定します。

戦略	入力例	出力
partial（デフォルト）	TR120000123456	**********3456（末尾の keep 文字を保持します。デフォルトは4文字です）
email	[email protected]	a***@site.com
full	任意の値	***

hiddenColumns とは異なり、マスキングした列も WHERE／GROUP BY で使用できます。そのため、完全に秘匿すべき情報には hiddenColumns を、識別可能な状態を保ちつつ公開は避けたい値には maskedColumns を使用してください。

出力形式

run_query と sample_table では、任意の format 引数を指定できます。値は json（デフォルト。結果オブジェクト全体）、csv、markdown のいずれかです。CSV と Markdown では、rows: N · Nms という簡潔なヘッダーが付いたテーブルが返されるため、トークン数を抑えたい場合や読みやすい出力が必要な場合に便利です。大きな結果を制限するには、maxCellChars と maxResultBytes を組み合わせてください。

本番データベースに接続して実行する

• パスワードがプロセス一覧に表示されないよう、接続文字列はコマンドラインではなく、DBRIDGE_DB_PATH 環境変数で渡します。
• 専用のデータベースロールを用意し、公開するテーブルのみに読み取り専用の権限を付与します。これが実質的なセキュリティ境界です。ガードは多層防御として機能します。
• 保守的な値で statementTimeoutMs、maxRows、maxCost を設定し、allowedTables を使ってレポート用テーブルのみを公開します。

ローカル開発

dbridge 自体を開発するには、リポジトリをクローンし、ソースからビルドします。

npm install
npm run build
npm run seed        # creates demo.db (a small store: products, customers, sales)
node dist/index.js demo.db

MCP Inspector で試す

npm run inspect

次に、Inspector の UI からツールを呼び出します。LLM や API キーは不要です。

テスト

npm test

変更履歴

CHANGELOG.md を参照してください。

ライセンス

MIT