MCP DB Connect

MCP DB Connect

Oracle Database、Microsoft SQL Server、PostgreSQL、MySQL/MariaDB、SQLite、MongoDB、Qdrant のベクトル検索に読み取り専用を優先してアクセスするための、汎用 MCP サーバーです。

このプロジェクトは、Model Context Protocol に対応した AI ツール向けに設計されています。プロジェクトにインストールし、YAML 設定を用意すると、安全なデータベースツールを AI クライアントに公開できます。

Oracle 接続では、デフォルトで Node.js の oracledb Thin モードを使用するため、ほとんどのデータベースで Oracle Instant Client は不要です。一部の Oracle データベースでは Thin モードで扱えない NCHAR 文字セットが使われているため、そのようなデータベースでは Oracle Client ライブラリを使う Oracle Thick モードが必要です。

デフォルトでは、プロジェクトディレクトリからコマンドを実行すると、次のファイルが自動的に使用されます。

• mcp-db.local.yml、次に mcp-db.yml、次に mcp-db.yaml
• .env

機能

• Oracle、MSSQL、PostgreSQL、MySQL/MariaDB、SQLite、MongoDB、Qdrant 用コネクター
• 1 つの設定ファイルで複数の名前付き接続を設定可能
• デフォルトで読み取り専用
• SQL の複数ステートメント実行をブロック
• 読み取り専用モードで MongoDB の $out と $merge をブロック
• 行数制限とクエリタイムアウト
• クエリ結果を Markdown テーブルで出力
• スキーマ／テーブルの許可リストと拒否リスト
• 機密フィールドのマスキング
• JSONL 監査ログ
• AI クライアントとデータベース接続の対話式セットアップウィザード
• セットアップ、初期化、検証、接続テスト、stdio／HTTP サーバー起動用 CLI
• Docker イメージ（マルチステージ Dockerfile。リリース時に GHCR に公開）

インストール

1. パッケージをインストールする

Node／TypeScript プロジェクト（ローカルインストール）：

npm install --save-dev mcp-db-connect

.NET、Python、またはその他の非 Node プロジェクト（グローバルインストール）：

npm install -g mcp-db-connect

2. セットアップウィザードを実行する

npx mcp-db-connect setup

ウィザードでは、設定する AI クライアントとデータベースを選択し、各データベースの接続文字列を入力します（DB ホスト、ホスティングプロバイダー、または既存のアプリ設定から取得できるものと同じ文字列です）。その後、すべての設定ファイルが自動的に書き込まれます。

3. 接続をテストする

npx mcp-db-connect test-connections

これで、AI クライアントがデータベースに接続されます。

ウィザードで作成されるもの

mcp-db.local.yml       # database connection config
.env                   # local secrets
.gitignore             # keeps secrets and local config out of git
.mcp.json              # Claude Code MCP config (if selected)
.codex/config.toml     # Codex CLI config (if selected)
.gemini/settings.json  # Gemini CLI config (if selected)
.kimi/mcp.json         # Kimi CLI config (if selected)

その他のセットアップ方法

明示的なフラグを指定して、ウィザードをスキップします。

npx mcp-db-connect setup --ai claude,codex --db mssql,mongodb

既存の設定項目を上書きします。

npx mcp-db-connect setup --force

stdio の代わりに HTTP MCP エンドポイントを起動します。

npx mcp-db-connect serve-http --host 127.0.0.1 --port 3000
npx mcp-db-connect serve-http --api-key-env MCP_DB_HTTP_API_KEY

AI クライアントの例

以下の例はすべて、AI CLI をアプリケーションのプロジェクトルートから起動することを前提としています。

Claude Code CLI

推奨される自動セットアップ：

mcp-db-connect setup --ai claude --db mssql

生成される .mcp.json では npx を使用するため、パッケージがグローバルとローカルのどちらにインストールされていても動作します。

グローバルインストール（npm install -g mcp-db-connect）

mcp-db-connect は PATH にあるため、直接使用できます。

claude mcp add --transport stdio db-connect --scope local -- mcp-db-connect start --project . --config ./mcp-db.local.yml --env ./.env

.mcp.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "mcp-db-connect",
      "args": ["start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

ローカルインストール（npm install --save-dev mcp-db-connect）

Claude Code が node_modules/.bin 内のバイナリを見つけられるように、npx を使用します。

claude mcp add --transport stdio db-connect --scope local -- npx mcp-db-connect start --project . --config ./mcp-db.local.yml --env ./.env

.mcp.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Codex CLI

推奨される自動セットアップ：

mcp-db-connect setup --ai codex --db mssql,oracle,mongodb
npm --prefix .\.mcp-tools\db-connect install
codex

プロジェクトの .codex/config.toml：

[mcp_servers.db-connect]
command = '.\.mcp-tools\db-connect\node_modules\.bin\mcp-db-connect.cmd'
args = ["start", "--project", ".", "--config", '.\mcp-db.local.yml', "--env", '.\.env']
enabled = true

[mcp_servers.db-connect.env]
LOG_LEVEL = "silent"

ウィザードで作成される .mcp-tools/db-connect/package.json ファイルは、npm の mcp-db-connect を使用します。プロジェクトごとに上記のインストールコマンドを一度実行してください。

Gemini CLI

推奨される自動セットアップ：

mcp-db-connect setup --ai gemini --db mongodb
gemini

プロジェクトの .gemini/settings.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Kimi CLI

推奨される自動セットアップ：

mcp-db-connect setup --ai kimi --db oracle
kimi --mcp-config-file .\.kimi\mcp.json

プロジェクトの .kimi/mcp.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Kimi CLI では kimi mcp add を使ってグローバル MCP サーバーを管理することもできますが、上記のプロジェクトローカルファイルを使用すると、このデータベース MCP を 1 つのプロジェクトに限定できます。

汎用 MCP JSON

共通の MCP JSON 形式を受け付けるクライアントの場合：

mcp-db-connect setup --ai generic --db mssql

.mcp-db-connect/mcp.json を使用します。

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Streamable HTTP クライアント

Streamable HTTP に対応した MCP クライアントまたはエージェントでは、このエンドポイントを使用します。

http://127.0.0.1:3000/mcp

ヘルスチェック：

http://127.0.0.1:3000/healthz

設定

security:
  defaultMaxRows: 100
  queryTimeoutMs: 10000
  blockMultiStatement: true
  allowWriteOperations: false
  maskColumns:
    - password
    - token
    - secret
    - api_key
  auditLogPath: ./logs/mcp-db-connect.audit.jsonl

connections:
  mssql_report:
    type: mssql
    host: 172.27.62.7
    port: 1433
    database: Internet
    username: report_reader
    passwordEnv: MSSQL_REPORT_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  mssql_write_model:
    type: mssql
    host: 172.27.62.8
    port: 1444
    database: InternetWrite
    username: writer_user
    passwordEnv: MSSQL_WRITE_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  oracle_local:
    type: oracle
    host: localhost
    port: 1521
    serviceName: ORCLPDB1
    username: app_readonly
    passwordEnv: ORACLE_PASSWORD
    clientMode: thin
    mode: readonly

  mssql_local:
    type: mssql
    host: localhost
    port: 1433
    database: appdb
    username: sa
    passwordEnv: MSSQL_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  mongo_local:
    type: mongodb
    uriEnv: MONGODB_URI
    database: appdb
    mode: readonly

  postgres_local:
    type: postgres
    host: localhost
    port: 5432
    database: appdb
    username: app_readonly
    passwordEnv: POSTGRES_PASSWORD
    mode: readonly

  mysql_local:
    type: mysql
    host: localhost
    port: 3306
    database: appdb
    username: app_readonly
    passwordEnv: MYSQL_PASSWORD
    mode: readonly

  qdrant_local:
    type: qdrant
    url: http://localhost:6333
    apiKeyEnv: QDRANT_API_KEY
    mode: readonly

  sqlite_local:
    type: sqlite
    file: ./data/appdb.sqlite
    mode: readonly

SQLiteにはホスト／ポート／ユーザー名がありません。fileにはデータベースファイルのパスを指定します（相対パスはプロセスの作業ディレクトリを基準に解決されます）。また、プロセス内で一時的に使用するデータベースとして:memory:も指定できます。

MongoDBでは、選択したポートを.envに保存するURIに含めます。例：

MONGODB_URI=mongodb://user:password@localhost:27018/appdb

OracleのThinモードとThickモード

Oracleのデフォルト設定ではclientMode: thinを使用し、Oracle Instant Clientは不要です。

connections:
  oracle_local:
    type: oracle
    host: localhost
    port: 1521
    serviceName: ORCLPDB1
    username: app_readonly
    passwordEnv: ORACLE_PASSWORD
    clientMode: thin

Oracle Instant Clientは必要ありません。データベースにNLS_NCHAR_CHARACTERSET = AL16UTF16が設定されたNCHAR／NVARCHAR2列がある場合、Thinモードで処理できるよう、コネクターがそれらの列をVARCHAR2にキャストするクエリをサーバー側で自動的に生成します。

個別のフィールドの代わりに接続文字列を使用する

Oracle、MSSQL、PostgreSQL、MySQL/MariaDBでは、host／port／database／usernameの代わりに、生の接続文字列も使用できます。

connections:
  mssql_from_string:
    type: mssql
    connectionStringEnv: MSSQL_FROM_STRING_CONNECTION_STRING
    mode: readonly

  oracle_from_string:
    type: oracle
    connectDescriptor: (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=10.20.30.15)(PORT=1521)))(CONNECT_DATA=(SERVER=POOLED)(SERVICE_NAME=DEMOPDB1)))
    username: demo_ora_user
    passwordEnv: ORACLE_FROM_STRING_PASSWORD
    mode: readonly

  postgres_from_string:
    type: postgres
    connectionStringEnv: POSTGRES_FROM_STRING_CONNECTION_STRING
    mode: readonly

  mysql_from_string:
    type: mysql
    connectionStringEnv: MYSQL_FROM_STRING_CONNECTION_STRING
    mode: readonly

connectionStringEnvには、.env内の完全なADO／tedious接続文字列（MSSQL）、postgres://user:password@host:5432/database URI（PostgreSQL）、またはmysql://user:password@host:3306/database URI（MySQL/MariaDB）を指定します（MongoDBのuriEnvと同じ規則です）。connectDescriptorにはOracleのTNS接続記述子またはEasy Connect文字列を指定します。これは秘密情報ではないため、.envに入れるのはパスワードのみです。セットアップウィザードは、貼り付けた接続文字列からこれらを自動生成します。また、上記の構造化されたhost／port／...フィールドを使って、どちらの形式も引き続き手動で記述できます。

PostgreSQLおよびMySQL/MariaDBの接続では、ssl: trueも指定できます（マネージドデータベースプロバイダーで一般的な自己署名証明書には、rejectUnauthorized: falseを指定します）。

環境変数による設定

設定を読み込むすべてのコマンド（start、serve-http、validate-config、test-connections）では、通常mcp-db.local.ymlに保存されるものと同じsecurity＋connections構造を持つ設定ドキュメント全体を、ファイルの代わりにYAMLまたはJSON形式で環境変数MCP_DB_CONFIGに指定できます。

export MCP_DB_CONFIG='
connections:
  postgres_demo:
    type: postgres
    host: db.example.com
    port: 5432
    database: appdb
    username: app_readonly
    password: change-me
    mode: readonly
'
mcp-db-connect serve-http --host 0.0.0.0 --port 3000

MCP_DB_CONFIGが設定されている場合、--config／mcp-db.local.yml／mcp-db.yml／mcp-db.yamlのファイル検索はすべてスキップされます。ファイルが存在する必要はありません。これにより、プロジェクトファイルをコンテナーにマウントできないコンテナープラットフォーム（Smithery.aiなどのホスト型MCPプラットフォーム）でも、このサーバーを実行できます。これらのプラットフォームでは、設定全体を1つの環境変数として注入します。シークレットはpassword:／connectionString:のように直接埋め込むことも、passwordEnv／connectionStringEnv／などを介して別の環境変数を参照することもできます。どちらの形式も、ファイルを使う場合とまったく同じように動作します。

ツール

SQL（Oracle + MSSQL + PostgreSQL + MySQL/MariaDB + SQLite）

• db_list_connections — 設定済みの接続を一覧表示します
• db_test_connection — 接続をテストします
• db_list_schemas — スキーマを一覧表示します
• db_list_tables — テーブルを一覧表示します
• db_describe_table — カラム（利用可能な場合はカタログのコメントを含む）、主キー、外部キー、インデックスについて説明します
• db_query — 読み取り専用の SQL クエリを実行します
• db_explain_query — SQL クエリの実行計画を返します
• db_count — オプションの WHERE 句を指定してテーブルの行数を数えます

db_query と db_explain_query は、バインドパラメーター用のオプションの params 配列を受け取ります。Oracle と PostgreSQL では位置指定バインドを使用します（Oracle は :1、:2、...、PostgreSQL は $1、$2、...）。MySQL/MariaDB と SQLite では、配列の順序に従って ? プレースホルダーを使用します。MSSQL には位置指定構文がないため、配列と同じ順序で @p1、@p2、... という名前付きパラメーターとしてバインドされます。

SQLite には main（およびアタッチされたデータベース）以外にスキーマ／データベースの概念がありません。db_list_schemas は PRAGMA database_list を使ってこれを反映し、db_explain_query はコストベースの実行計画ではなく EXPLAIN QUERY PLAN を実行します。

db_describe_table には、データベースで設定されている場合、各カラムのカタログコメント／説明が含まれます（Oracle の all_col_comments、PostgreSQL の COMMENT ON COLUMN、MySQL/MariaDB の COLUMN_COMMENT、MSSQL の MS_Description 拡張プロパティ）。出力の comment カラムは、実際にコメントが設定されているカラムが少なくとも1つある場合にのみ表示されます。SQLite にはコメントの仕組みがないため、ここに値が設定されることはありません。

MongoDB

• db_list_connections — 設定済みの接続を一覧表示します
• db_test_connection — 接続をテストします
• db_list_schemas — データベースを一覧表示します
• db_list_tables — コレクションを一覧表示します
• db_describe_table — コレクションのフィールドをサンプリングします
• db_mongo_find — 読み取り専用の検索操作を実行します
• db_mongo_aggregate — 読み取り専用の集計パイプラインを実行します
• db_mongo_count — オプションのフィルターを指定してドキュメント数を数えます
• db_mongo_get_indexes — コレクションのインデックスを一覧表示します
• db_mongo_explain_find — 検索操作の実行計画を返します
• db_mongo_explain_aggregate — 集計パイプラインの実行計画を返します
• db_mongo_insert — 1つ以上のドキュメントを挿入します
• db_mongo_update — フィルターに一致するドキュメントを更新します（すべての一致を対象にする場合は many: true、それ以外の場合は最初の1件のみ）
• db_mongo_delete — フィルターに一致するドキュメントを削除します（すべての一致を対象にする場合は many: true、それ以外の場合は最初の1件のみ）

db_mongo_insert／db_mongo_update／db_mongo_delete は、接続に mode: readwrite と security.allowWriteOperations: true の両方が設定されていない限りブロックされます。これは、SQL コネクターで書き込み SQL 文が制御される方法に準じています。また、db_mongo_update と db_mongo_delete には空でない filter も必要です。これにより、誤って {} を指定してコレクション全体が黙って更新または削除されることを防ぎます。

db_describe_table はドキュメントをサンプリングして MongoDB のカラム型を推定します。サンプルサイズのデフォルトは20で、接続ごとに describeSampleSize を設定するか、ツールの sampleSize 引数で呼び出しごとに上書きできます。

connections:
  mongo_local:
    type: mongodb
    uriEnv: MONGODB_URI
    database: appdb
    describeSampleSize: 100
    mode: readonly

db_mongo_find はページネーション用のオプションの skip を受け取ります（最初の N 件の一致ドキュメントをスキップしてから、ページサイズとして maxRows を適用します）。

Qdrant（ベクトル検索）

• db_list_connections — 設定済みの接続を一覧表示します
• db_test_connection — 接続をテストします
• db_list_tables — コレクションを一覧表示します
• db_describe_table — コレクションのベクトル設定とペイロードフィールドの型を表示します
• db_qdrant_search — オプションのフィルターとスコアしきい値を指定して、ベクトル類似検索を実行します
• db_qdrant_scroll — ベクトル検索を使わずにポイントを参照またはフィルタリングします
• db_qdrant_count — オプションのフィルターを指定してポイント数をカウントします

Qdrant のコレクションはスキーマやデータベースにグループ化されていないため、Qdrant 接続では db_list_schemas は空のリストを返します。

db_qdrant_scroll は、コレクション全体のページングに対応しています。ポイントが残っている場合、各応答には Next offset の行が含まれます。続きから取得するには、次の呼び出しでその値を offset 引数に渡してください。最初から取得するには、offset を省略します。

クエリ結果ツールは、次のようなテーブルを返します。

Rows: 2

| id | name |
| --- | --- |
| 1 | Alice |
| 2 | Bob |

CLI コマンド

• mcp-db-connect setup
• mcp-db-connect init
• mcp-db-connect ai-config
• mcp-db-connect validate-config
• mcp-db-connect test-connections
• mcp-db-connect start
• mcp-db-connect serve-http --host 127.0.0.1 --port 3000
• mcp-db-connect serve-http --api-key-env MCP_DB_HTTP_API_KEY
• mcp-db-connect update

更新

start と serve-http は、npm を1日1回確認し（キャッシュされ、ブロッキングせず、オフラインの場合は通知なしでスキップされます）、新しいバージョンがあれば標準エラー出力に通知を表示します。標準出力には一切触れないため、stdio トランスポートでも安全です。確認対象は ^<your current version> の範囲内、つまり現在の 0.x マイナーラインのみです（たとえば、0.1.21 の場合は 0.1.22、0.1.23 などが対象となり、0.2.0 は対象になりません）。このプロジェクトはまだ 1.0.0 に達していないため、マイナーバージョンの更新でも破壊的変更が含まれる可能性があります。範囲を狭くすることで、気づかないうちにそのようなバージョンへ更新されるのを防ぎます。

次のコマンドを実行して、自分で更新してください。

mcp-db-connect update              # checks and installs, if available
mcp-db-connect update --check-only # only checks, doesn't install
mcp-db-connect update --range "^0.2.0"  # override the range, e.g. to opt into a new minor line deliberately

パッケージがグローバルにインストールされているか、ローカルプロジェクトの依存関係としてインストールされているかを検出し、該当する npm install コマンドを実行します。完全にサイレントなバックグラウンド自動インストールはありません。更新には、常にこの明示的なコマンド（または独自の npm install -g mcp-db-connect@latest / npm install --save-dev mcp-db-connect@latest）が必要です。

Docker

リポジトリのルートにあるマルチステージの Dockerfile は、CLI をスタンドアロンイメージにビルドします。接続設定はイメージに組み込まずファイルで管理するため、コンテナにはプロジェクトの mcp-db.local.yml と .env をマウントする必要があります。

公開済みのイメージを取得します（各リリース時に .github/workflows/release.yml によってビルドされ、GHCR にプッシュされます）。

docker pull ghcr.io/phatngoit/mcp-db-connect:latest

または、ローカルでビルドします。

docker build -t mcp-db-connect .

プロジェクトの設定をマウントして、stdio 経由で実行します（コンテナを直接起動する MCP クライアント向け）。ローカルビルドの代わりに公開済みイメージを使うには、mcp-db-connect を ghcr.io/phatngoit/mcp-db-connect:latest に置き換えてください。

docker run -i --rm \
  -v "$(pwd)/mcp-db.local.yml:/app/project/mcp-db.local.yml:ro" \
  -v "$(pwd)/.env:/app/project/.env:ro" \
  mcp-db-connect start --project /app/project

ポートを公開して、Streamable HTTP トランスポートを実行します。

docker run --rm -p 3000:3000 \
  -v "$(pwd)/mcp-db.local.yml:/app/project/mcp-db.local.yml:ro" \
  -v "$(pwd)/.env:/app/project/.env:ro" \
  mcp-db-connect serve-http --project /app/project --host 0.0.0.0 --port 3000

または、examples/docker-compose.server.yml の例を使います。この例では、イメージをビルドし、カレントディレクトリの mcp-db.local.yml／.env をマウントします。

docker compose -f examples/docker-compose.server.yml up --build

クラウド／コンテナプラットフォームでのホスティング

ファイルマウントの代わりに MCP_DB_CONFIG を設定すれば、ファイルをマウントする必要はありません（環境変数による設定を参照）。イメージのエントリーポイント（docker-entrypoint.sh）は、PORT 環境変数が存在する場合、stdio から Streamable HTTP トランスポートへ自動的に切り替わります。これは Smithery.ai、Railway、Render、Fly.io などのプラットフォームで使われる規約であり、コマンドを上書きせずに 0.0.0.0:$PORT にバインドします。

docker run -e PORT=8080 -e MCP_DB_CONFIG="$(cat mcp-db.local.yml)" -p 8080:8080 \
  ghcr.io/phatngoit/mcp-db-connect:latest

セキュリティのデフォルト設定

このサーバーは意図的に保守的な設定になっています。

• 接続はデフォルトで readonly です
• グローバル設定と接続設定で書き込みが許可されていない限り、SQL の書き込みキーワードと DDL キーワードはブロックされます
• SQL の複数ステートメント実行はブロックされます
• グローバル設定と接続設定で書き込みが許可されていない限り、MongoDB の集計における書き込みステージと db_mongo_insert／db_mongo_update／db_mongo_delete はブロックされます
• db_mongo_update／db_mongo_delete には空でないフィルターが必要なため、誤ってコレクション全体に影響することはありません
• 結果の行数は設定で上限が設けられています
• 機密フィールドは再帰的にマスクされます

可能な限り権限を絞ったデータベースアカウントを使用してください。MCP レイヤーは安全対策であり、データベースレベルの権限設定の代わりにはなりません。

レジストリ

• Official MCP Registry — リポジトリのルートにある server.json を通じて、io.github.phatngoit/mcp-db-connect として登録されています。リリースワークフロー（.github/workflows/release.yml）により、npm リリースのたびに GitHub Actions OIDC を使用してこのレジストリに自動公開されます（保存済みのトークンは不要です）。
• Glama.ai — このリポジトリをクロールしてインデックスに登録されています。手動で申請済みで、マニフェストファイルは不要です。
• Smithery.ai — まだ申請されていません。障害となっていた要件は解決済みです。ghcr.io/phatngoit/mcp-db-connect に公開済みの Dockerfile、リポジトリのルートにあるコンテナランタイム用マニフェスト smithery.yaml、MCP_DB_CONFIG 環境変数による設定（ファイルのマウントは不要）、HTTP トランスポートに自動で切り替わる PORT 対応のエントリーポイントが揃っています。申請には、Smithery の GitHub App を通じて smithery.ai/new からこのリポジトリを接続するという、手動での初回作業が必要です。また、執筆時点では smithery.yaml の正確なフィールドを独自に確認できなかったため、事前に Smithery の最新ドキュメントと照合してください。

ロードマップ

• OpenTelemetry によるトレーシング
• シークレットマネージャーとの連携（AWS Secrets Manager、Azure Key Vault、HashiCorp Vault）