MCP Db Bridge

🚀 mcp-db-bridge

mcp-db-bridgeは、粒度の細かい権限設定、マルチDBサポート、クラウド対応のSSL/TLSを備えた、MySQL、PostgreSQL、SQLite用のMCP（Model Context Protocol）サーバーです。アダプターパターンを用いて構築されており、拡張性に優れています。

🚀 クイックスタート

まずは、mcp-db-bridgeをインストールします。

npm install mcp-db-bridge
# または
pnpm add mcp-db-bridge

それぞれのデータベースに合わせて.envファイルを設定します。

MySQL (ローカル)

# .env
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=mydb

PostgreSQL (ローカル)

# .env
DB_TYPE=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=mydb

SQLite (インメモリ)

# .env
DB_TYPE=sqlite
SQLITE_DB=:memory:

設定が完了したら、サーバーを起動します。

pnpm build
pnpm start
# または
node dist/index.js

✨ 主な機能

• 🔌 マルチデータベース対応：MySQL、PostgreSQL、SQLiteをサポートします。
• 🏗️ アダプターパターン：クリーンで拡張性の高いアーキテクチャで構築されています。
• ☁️ クラウド対応：AWS RDS、Google Cloud SQL、Azure DatabaseなどのクラウドデータベースにSSL/TLSを使用して接続できます。
• 🔒 セキュリティ重視：読み取り専用モードと粒度の細かいスキーマ権限設定により、データの安全性を確保します。
• 🌐 マルチDBモード：単一の接続で複数のデータベースやスキーマに同時にアクセスできます。
• 🔄 トランザクション管理：自動的にBEGIN、COMMIT、ROLLBACKを行います。
• 🚀 HTTPモード：オプションでリモートHTTPサーバー（Express）を使用できます。

📦 インストール

mcp-db-bridgeをインストールするには、以下のコマンドを実行します。

npm install mcp-db-bridge
# または
pnpm add mcp-db-bridge

💻 使用例

基本的な使用法

以下は、それぞれのデータベースに接続するための基本的な.envファイルの設定例です。

MySQL (ローカル)

# .env
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=mydb

PostgreSQL (ローカル)

# .env
DB_TYPE=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=mydb

SQLite (インメモリ)

# .env
DB_TYPE=sqlite
SQLITE_DB=:memory:

高度な使用法

マルチDBモードでの使用

DB_NAMEを空にすることで、マルチDBモードを有効にできます。

DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=                # 空 = マルチDBモード

書き込み保護

デフォルトでは、マルチDBモードはセキュリティ上の理由から読み取り専用です。書き込みを許可するには、以下の設定を行います。

MULTI_DB_WRITE_MODE=true  # ⚠️ 注意して使用してください！

推奨される方法は、SCHEMA_*_PERMISSIONSを使用して粒度の細かい制御を行うことです。

# 粒度の細かい権限設定を持つマルチDB
DB_TYPE=mysql
DB_NAME=                                    # マルチDBモード
ALLOW_INSERT_OPERATION=false                # グローバル: 禁止
SCHEMA_INSERT_PERMISSIONS=test_db:true      # 例外: test_dbは挿入できる
SCHEMA_UPDATE_PERMISSIONS=test_db:true      # 例外: test_dbは更新できる
SCHEMA_DELETE_PERMISSIONS=test_db:false     # test_db: DELETEは禁止
SCHEMA_DDL_PERMISSIONS=test_db:true         # test_db: DDLは許可

📚 詳細ドキュメント

設定

データベースタイプ

DB_TYPE=mysql          # MySQL
DB_TYPE=postgresql     # PostgreSQL
DB_TYPE=sqlite         # SQLite

接続設定

全データベース共通

DB_HOST=127.0.0.1
DB_PORT=3306           # MySQL: 3306, PostgreSQL: 5432
DB_USER=root
DB_PASS=password
DB_NAME=mydb           # マルチDBモードの場合は空にする
DB_CONNECTION_LIMIT=10

MySQL固有の設定 (下位互換性)

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASS=password
MYSQL_DB=mydb
MYSQL_SOCKET_PATH=/tmp/mysql.sock  # Unixソケット (host/portより優先)

PostgreSQL固有の設定

POSTGRESQL_HOST=127.0.0.1
POSTGRESQL_PORT=5432
POSTGRESQL_DB=mydb

SQLite固有の設定

SQLITE_DB=:memory:              # インメモリデータベース
SQLITE_DB=/var/lib/app/data.db  # ファイルベースのデータベース

セキュリティと権限

読み取り専用モード

アプリケーションレベルですべての書き込み操作をブロックします。

DB_READ_ONLY_MODE=true

グローバルな書き込み権限

操作の種類ごとに細かく制御できます（グローバルに適用されます）。

ALLOW_INSERT_OPERATION=true   # INSERTを許可
ALLOW_UPDATE_OPERATION=true   # UPDATEを許可
ALLOW_DELETE_OPERATION=false  # DELETEをブロック
ALLOW_DDL_OPERATION=false     # CREATE/ALTER/DROP/TRUNCATEをブロック

スキーマ固有の権限

特定のスキーマに対してグローバルな権限を上書きできます。

# 形式: "schema1:true,schema2:false,schema3:true"
SCHEMA_INSERT_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_UPDATE_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_DELETE_PERMISSIONS=prod_db:false,test_db:false,staging_db:false
SCHEMA_DDL_PERMISSIONS=prod_db:false,test_db:true,staging_db:false

動作原理:

• スキーマに特定の権限が設定されている場合は、その権限を使用します。
• それ以外の場合は、グローバルなフラグを使用します。

例:

# グローバル: INSERTはブロック
ALLOW_INSERT_OPERATION=false

# test_dbは挿入できるが、prod_dbはできない
SCHEMA_INSERT_PERMISSIONS=test_db:true,prod_db:false

# 結果:
# - test_dbでのINSERT: ✅ 許可 (スキーマ権限)
# - prod_dbでのINSERT: ❌ ブロック (スキーマ権限)
# - other_dbでのINSERT: ❌ ブロック (グローバル権限)

クラウドデータベースのSSL/TLS設定

AWS RDS (MySQL/PostgreSQL)

DB_TYPE=mysql
DB_HOST=myinstance.123456789012.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true
# オプション: DB_SSL_CA=/path/to/aws-rds-ca-cert.pem

Google Cloud SQL (PostgreSQL)

DB_TYPE=postgresql
DB_HOST=34.123.45.67
DB_PORT=5432
DB_SSL=true
DB_SSL_CA=/path/to/server-ca.pem
DB_SSL_CERT=/path/to/client-cert.pem
DB_SSL_KEY=/path/to/client-key.pem

Azure Database for MySQL

DB_TYPE=mysql
DB_HOST=myserver.mysql.database.azure.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true

リモートMCP (HTTPサーバー)

認証付きでHTTP経由でMCPサーバーを実行します。

# .env
IS_REMOTE_MCP=true
REMOTE_SECRET_KEY=your-secret-key-here
PORT=3000

エンドポイント: POST http://localhost:3000/mcp

ヘッダー: Authorization: Bearer your-secret-key-here

🔧 技術詳細

アーキテクチャ

src/
├── db/
│   ├── adapters/
│   │   ├── types.ts              # インターフェースと型定義
│   │   ├── factory.ts            # ファクトリパターン
│   │   ├── mysql.adapter.ts      # mysql2を使用したMySQLアダプター
│   │   ├── postgresql.adapter.ts # pgを使用したPostgreSQLアダプター
│   │   └── sqlite.adapter.ts     # better-sqlite3を使用したSQLiteアダプター
│   ├── index.ts                  # コアクエリハンドラー
│   ├── utils.ts                  # SQL解析 (node-sql-parser)
│   └── permissions.ts            # スキーマ権限チェック
├── config/
│   └── index.ts                  # 環境設定
├── utils/
│   └── index.ts                  # ログ記録とユーティリティ
└── types/
    └── index.ts                  # 型定義

アダプターパターン

各アダプターはDatabaseAdapterインターフェースを実装しています。

export interface DatabaseAdapter {
  readonly type: DatabaseType;
  createPool(config: ConnectionConfig): Promise<DatabasePool>;
  executeQuery<T>(pool: DatabasePool, sql: string, params?: any[]): Promise<T>;
  setReadOnly(connection: DatabaseConnection): Promise<void>;
  unsetReadOnly(connection: DatabaseConnection): Promise<void>;
  normalizeResult(result: any): NormalizedResult;
  supportsReadOnlyMode(): boolean;
}

トランザクションフロー

読み取り操作:

BEGIN → SET TRANSACTION READ ONLY → QUERY → ROLLBACK → RESET TO READ WRITE

書き込み操作:

BEGIN → QUERY → COMMIT (またはエラー時はROLLBACK)

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。

クレジット

• mcp-server-mysql: @benborla