Universal DB (read-only)

universal-db-mcp

クイックスタート · ツール · セキュリティモデル · オフラインインストール · ドキュメント · ランディングページ · 脆弱性を報告

AI エージェントに、データベースへの読み取り専用アクセスを安全に提供します。 universal-db-mcp はMCPサーバーです。 Claude Code、Cursor、VS Code、または任意の MCP クライアントが、宣言されたデータベースのみを検出、文書化、プロファイリング、検索、クエリできるようにします。実行前にすべてのステートメントを解析し、単一の読み取り処理であることを必須とします。読み取り専用セッションで実行し、機密情報に見える列をマスキングし、すべての呼び出しを監査します。書き込みは推奨しないのではなく、拒否します。サーバーは LLM を呼び出さず、テレメトリーを送信せず、実行時に何もインストールしないため、インターネットにまったく接続できないネットワークでも動作します。

**ステータス：**本番環境向けのセキュリティレビューと、その後の 3 回のコードレビューを経て強化済みです（2026-09/10）。IMPLEMENTATION_STATUS.mdには、実装済みの内容、検証済みの内容とその方法、未解決の項目が正直に記録されています。ここでの主張は、ゲートとtest-evidence/で実証されている内容に限定されています。

機能

エンジン（以下の各バージョンはバージョンマトリックスに合格しています。scripts/version_matrix/、結果は test-evidence/version-matrix/ にあります）：

エンジン	検証済みバージョン
PostgreSQL	12、13、14、15、16、17
MySQL / MariaDB	MySQL 5.7、8.0、8.4；MariaDB 10.6、11.4
ClickHouse	23.8、24.3、24.8、25.3
Oracle	18c、21c、23（シンモード）；11g、18c、23（レガシーパスワード検証子用のシックモード）
SQL Server	2017、2019、2022
Db2	11.5.8、11.5.9
SQLite	CPython ビルドの SQLite

29 個のツール（仕様は docs/tools.md を参照）：

• 接続： db_list_connections、db_test_connection、db_get_capabilities。
• カタログ： db_list_catalogs、db_list_databases、db_list_schemas、 db_list_tables、db_get_table、db_list_columns、db_list_views、 db_list_synonyms、db_list_routines、db_list_indexes、 db_get_relationships、db_get_statistics、db_search_metadata、 db_get_catalog。
• データの読み取り： db_validate_query、db_query、db_sample_table、 db_explain（実行ではなく、実行計画を取得）、db_get_query_history。
• 検出、レビュー、ドキュメント作成： db_profile_table、 db_search_values（SQL を記述せずに、テーブルや接続をまたいで値を検索）、 db_infer_relationships、db_review_schema（優先度付きの最適化に関する指摘）、 db_document_schema（Markdown 形式のデータディクショナリ）。
• フェデレーション読み取り： db_federated_query（1 つのステートメントを実行するか、接続ごとに 1 つのステートメントを実行して結果を統合）および db_federated_join（2 つの接続間で実行する、範囲を制限したハッシュ結合）。

データベースを安全に保つ仕組み

多層防御を採用しています。詳細と制限事項については、docs/security.md と docs/session-safety.md を参照してください。

1. データベースのログインが主な制御手段です。 すべての接続に、allowed_schemas で指定したスキーマに限定した SELECT 専用ログインを設定してください。例外は Db2 の db_explain です。DBA が用意した explain テーブルに実行計画の行を書き込み、読み戻して削除するため、そのログインには、それらのテーブルに対する INSERT、SELECT、DELETE も必要です。ただし、権限が必要なのはそのテーブルだけです（Oracle の実行計画はセッション専用の PLAN_TABLE に書き込まれるため、権限付与は不要です）。機密列を実際に保護するには、列レベルの権限またはビューを使用してください。
2. 読み取り専用セッションです。 デフォルトで有効になっており、PostgreSQL、MySQL/MariaDB、ClickHouse、SQLite ではサーバー自体がこれを強制します。Db2 は UR、SQL Server は READ UNCOMMITTED で動作するため、読み取り時に共有ロックを取得しません。書き込みモードはありません。security.read_only: false、allow_write_operations: true、接続の read_only: false は、設定の読み込み時に拒否されます。また、各セッションでは、サーバーがステートメントを字句解析する方法を決める設定（MySQL の sql_mode、PostgreSQL の standard_conforming_strings、SQL Server の QUOTED_IDENTIFIER など）が固定されるため、サーバーはガードが解析した内容とまったく同じ内容を読み取ります。
3. SQL ガードは、各ステートメントを接続先の方言で解析し、読み取りステートメントを 1 つだけ受け入れます。解析できないものはすべて拒否されます。空でない allowed_schemas が設定されている場合、すべてのテーブルでスキーマを明示する必要があります（SELECT * FROM ocean.buoys のように記述し、SELECT * FROM buoys のようには記述しません）。そうしないと、使用するスキーマがエンジンによって選択されてしまうためです。Oracle、Db2、PostgreSQL では、CTE 名と引用符で囲まれていないテーブル名は ASCII 文字でなければなりません。他のセッションの SQL、列統計、保存された認証情報を表示するビューは、allowed_system_schemas で許可されている内容にかかわらず拒否されます。Oracle の SYS.DUAL と Db2 の SYSIBM.SYSDUMMY1 から SYSDUMMY4 は常に読み取り可能です。バインドパラメーターは、検証された値のままドライバーに渡されます。
4. 証明できない場合は拒否するマスキングです。 組み込みのパターンと security.mask_columns に一致する列は、各出力値の由来に基づいてマスキングされます。マスキング対象の列を含むテーブルに対するステートメントは、解析によって完全に証明できる形式（列、式、集計、ウィンドウ関数、結合、CTE、サブクエリ、UNION、列挙されたテーブルに対する *）の場合に限り受け入れられます。それ以外は、該当する構文を明示して実行前に拒否されます。述語はマスキングされません。マスキング対象の列を使った WHERE 句で結果を絞り込むことは可能です。
5. 上限設定、サニタイズ、監査を行います。 行数、バイト数、セル数、実行時間に上限を設けています。ClickHouse ではクエリごとにメモリー使用量を制限します（デフォルトは 2 GiB、options.max_memory_usage）。サイズ上限は解析前に確認し、ドライバーのエラーテキストはサニタイズされます。すべての呼び出しは監査され、デフォルトではプラットフォームの状態ディレクトリに記録されます（サービスの設定では /var/log/universal-db-mcp/audit.jsonl、Windows では %ProgramData%\UniversalDB MCP\logs\audit.jsonl、ユーザーごとの設定では ~/.universal-db-mcp/audit.jsonl）。
6. stdio はセキュリティ境界ではありません。 stdio で登録すると、エージェント内でサーバーがユーザーと同じ権限で実行されます。そのため、エージェントがシェルコマンドを実行したりファイルを読み取ったりできる場合、~/.universal-db-mcp/secrets/ にある認証情報を読み取り、ガードを介さずに直接接続できます。SELECT 専用ログインを使用するか、サーバーを別のサービスアカウントで HTTP モード（ベアラートークン、リバースプロキシ経由）で実行してください。

クイックスタート

PyPI から

uv tool install 'udbmcp[all]'   # or: pipx install 'udbmcp[all]'
udbmcp add-connection            # writes ~/.universal-db-mcp/config.yaml, secrets in private files beside it
udbmcp configure-agents          # registers it with Claude Code, Claude Desktop, Cursor, VS Code, Cline

[all] には PostgreSQL、MySQL/MariaDB、ClickHouse、Oracle（thin モード）のドライバーが含まれます。SQLite にはドライバーは不要です。SQL Server（udbmcp[mssql]）と Db2（udbmcp[db2]）にも、それぞれのベンダーのクライアントライブラリが必要です。PyPI 上の wheel は、リリースの署名済みバンドルに含まれるものと同じで、PEP 740 の証明書とともにアップロードされています。configure-agents は、このようなインストールから実行し、uvx 経由では実行しないでください。uvx は uv が削除するキャッシュから実行されるため、configure-agents はその場所にあるインタープリターの登録を拒否します。

ソースから

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e '.[dev]'
.venv/bin/python examples/sqlite-demo/create_demo.py   # synthetic fixture
UDBMCP_CONFIG=examples/sqlite-demo/config.yaml .venv/bin/python -m universal_db_mcp serve --transport stdio

.venv/bin/udbmcp configure-agents を使って、サーバーをエージェントに登録します（Claude Code、Claude Desktop、Cursor、VS Code、Cline など。docs/claude-code-integration.md）。起動コマンドには python -I（分離モード）が書き込まれるため、上記のようにパッケージとその依存関係を仮想環境にインストールする必要があります。pip install --user や PYTHONPATH のみを使った設定は拒否されます。ユーザーが読み取り可能な場合はシステム設定（Windows では /etc/universal-db-mcp/config.yaml、%ProgramData%\UniversalDB MCP\config.yaml）を登録し、そうでない場合はユーザーごとの ~/.universal-db-mcp/config.yaml を登録します。別の設定を選ぶには、事前に絶対パスを UDBMCP_CONFIG に設定してください。.deb にはすべてのユーザーが読み取り可能なシステム設定が含まれています。そのため、.deb のホストでは、先に権限を root:udbmcp 0640 に設定してください（docs/claude-code-integration.md）。

udbmcp add-connection は対話形式で接続を追加し、シークレットをプライベートな権限で保存します。udbmcp doctor は設定とシークレットを確認し、--connectivity を指定すると、すべてのデータベースも確認します。

コンテナーイメージを使う場合

docker pull ghcr.io/alghanim/universal-db-mcp:0.2.0
gh attestation verify oci://ghcr.io/alghanim/universal-db-mcp:0.2.0 --repo alghanim/universal-db-mcp

公式の MCP Registry には io.github.alghanim/universal-db-mcp として掲載されているため、レジストリーを閲覧できるクライアントからインストールできます。設定とシークレットを読み取り専用でマウントし、docs/offline-deployment.md の「コンテナーモード」の説明に従って、stdio または HTTP 経由で実行してください。このイメージには SQL Server ドライバーは含まれていません。同じセクションに、Microsoft のドライバーを追加する方法が記載されています。

最小限の接続設定

connections:
  sales:
    type: postgres
    host: pg.example.internal
    port: 5432
    database: sales
    username_file: /etc/universal-db-mcp/secrets/sales.user   # 0600, owned by the service account
    password_file: /etc/universal-db-mcp/secrets/sales.pw
    allowed_schemas: [reporting]
    tls:
      enabled: true
      ca_file: /etc/universal-db-mcp/ca/internal-ca.pem

config.example.yaml には、エンジンごとのすべての設定が記載されています。

オフライン（エアギャップ環境）でのインストール

成果物	プラットフォーム	ステータス
.deb	Ubuntu 24.04 x86-64	リリースゲート：ネットワーク接続なしでインストール、アップグレード、ロールバック、拒否ケースを確認
.pkg	macOS arm64	リリースゲートに合格。未署名（Developer ID はまだありません）
.msi	Windows x64	WiX でコンパイルされ、カスタムアクションは PowerShell でテスト済み。Windows ホストではまだ実行しないでください
オフラインバンドル	上記のいずれか	リリースキーで署名済み。scripts/install_offline.sh
コンテナーイメージ	linux/amd64、ネットワーク接続されたホスト	ghcr.io/alghanim/universal-db-mcp。各リリースの署名済みバンドルから CI がビルドし、来歴証明書を付与（docs/offline-deployment.md）

docs/offline-deployment.md を参照してください。リリース用 USB メモリーからインストールするサイトについては、docs/site-upgrade-runbook.md も参照してください（scripts/package/release_usb.sh で作成できます）。要点は次のとおりです。

# staging machine (authorized for network): the bundle is signed with the release
# key (docs/offline-build.md; scripts/package/release_usb.sh builds a whole stick)
python scripts/prepare_offline_bundle.py --profile linux-x86_64-ubuntu24.04-cp312 --out out/bundle \
  --signing-key udbmcp-release.pem

# target machine (offline), after the trust bootstrap in docs/offline-deployment.md,
# which installs the public key once its fingerprint matches one received out of band:
sudo UDBMCP_RELEASE_PUBKEY=/etc/universal-db-mcp/keys/release.pub.pem \
  bash /usr/local/lib/udbmcp-trust/install_offline.sh out/bundle/universal-db-mcp-*/ /opt/universal-db-mcp
# the installer does not create the config: start from the bundle's template, readable by the service only
sudo install -m 640 -o root -g udbmcp out/bundle/universal-db-mcp-*/config-templates/config.yaml /etc/universal-db-mcp/config.yaml
sudo -u udbmcp /opt/universal-db-mcp/venv/bin/python -m universal_db_mcp doctor --config /etc/universal-db-mcp/config.yaml

バンドルや USB メモリーに含まれるものは、インストール済みのリリースキーに照らして Ed25519 署名が検証されるまで実行されません。インストーラーは、署名された release_seq がインストール済みリリースより古いバンドルを拒否します。ダウングレードを行うには、スクリプトでは --allow-downgrade、.deb では UDBMCP_ALLOW_DOWNGRADE=1、.pkg では指定されたワンショットのフラグファイルを使用します。このリリースの MSI では、新しいバージョンをアンインストールした後に UDBMCP_ALLOW_DOWNGRADE=1 を指定してください（Windows Installer は、新しいバージョンの上書きインストールとして古い MSI を拒否します）。コンテナーモードでは、scripts/load_images_offline.sh が root 所有のリリース記録（/var/lib/universal-db-mcp/release.json）を保持し、同様に古いバンドルを拒否します。

検証

• テスト： 12,000 件を超える単体テストを、GitHub Actions CI では ubuntu-24.04 で、ローカルでは macOS で実行しています。ruff と mypy --strict の チェックもすべて通過しています。最新の件数は IMPLEMENTATION_STATUS.md（セクション 3f）に記録されています。
• 実データベース： 上記のバージョンマトリックス、および scripts/fixtures/start_mock_dbs.sh のモックデータベースを対象とする scripts/live_evidence.py（docs/mock-environment.md）。
• パッケージ： .deb と .pkg のリリースゲート、およびオフラインアップグレード ゲート（docs/acceptance-tests.md）。
• サプライチェーン： 各プラットフォーム向けの、ハッシュ検証済みの固定ロックファイルを 使用し、pip-audit でチェックしています。
• ファジング： SQL ガードは Atheris（tests/fuzz/）で、main への各プッシュ後と毎週 ファジングしています。入力を受け入れることも、明確に拒否することもできない場合、実行は失敗します。

まだどこでも検証されていないもの：実際の Windows ホスト上での MSI、および実際の macOS での .pkg インストーラーの実行。

開発

.venv/bin/python -m pytest -o addopts='' -q tests                 # the whole suite
UDBMCP_LIVE_FIXTURES=1 UDBMCP_DOCKER_TESTS=1 \
  .venv/bin/python -m pytest -o addopts='' -q tests               # plus the live-database and container tests
.venv/bin/ruff check src tests scripts && .venv/bin/mypy --strict src

ローカルのモックデータベースを使用するテストは、UDBMCP_LIVE_FIXTURES=1 の場合のみ実行されるため、 パッケージゲートが一時停止中または存在しないデータベースを待ち続けることはありません。実際の dpkg を使うコンテナーシーケンスは、UDBMCP_DOCKER_TESTS=1 の場合のみ実行されます。バンドルビルダーのテストには venv 内の pip が必要です。uv sync の後、次を実行してください。 uv pip install --python .venv/bin/python --require-hashes -r .github/ci-pip-requirements.txt

CI。 .github/workflows/ci.yml は GitHub Actions のワークフローです（ubuntu-24.04、 CPython 3.12）。単体テストスイート（pwsh で実行する MSI カスタムアクションのテストを含む）、ruff、 mypy --strict、prepare_offline_bundle.py --check-locks、およびすべてのロックファイルを対象とする pip-audit を実行します。Actions はコミット SHA で固定されています。すべてのプルリクエストと main へのすべてのプッシュで、2 つのジョブを同時に実行します。最も時間のかかるインストーラーと パッケージングのテストファイルは installer-tests で実行し、残りのテストとその他すべてのチェックは checks で実行します。.github/workflows/audit.yml は毎週同じ pip-audit を実行するため、 コミット間に新しいアドバイザリが公開された場合も実行が失敗します。Dependabot は月次でグループ化された更新を提案します。 tests/unit/test_hardening_2026_09_27_ci_hygiene.py は CI の設定自体を検査します（Actions の固定、 pytest オプション、2 つのジョブを合わせて全テストを 1 回ずつ実行すること、conftest やヘルパー内に隠されたスキップやフックがないこと、ツリー内にコンパイル済みファイルやシンボリックリンクがないこと）。これは警告を発する仕組みであり、サンドボックスではないため、conftest、テストヘルパー、CI ファイルの変更には引き続きレビューが必要です。Dependabot が requirements/runtime.in を更新した後は、ロックファイルを更新してレビューしてください （docs/offline-build.md）。

ドキュメント一覧

ドキュメント	目的
docs/architecture.md	コンポーネント、データフロー、プロセス境界、実行制限
docs/security.md	脅威モデル、ポリシー、マスキング、監査、シークレット、TLS
docs/tools.md	MCP ツールの仕様（29 個の db_* ツール）
docs/session-safety.md	エージェントによる読み取りが本番環境に影響しないよう、各接続がサーバーセッションに対して行う処理
docs/driver-matrix.md	エンジンごとのドライバー、ネイティブ依存関係、プロビジョニング SQL、テスト状況
docs/oracle-connect-modes.md	Oracle のシックモード（レガシーのパスワード検証子）、SID と TNS エイリアスによる接続、TLS
docs/db2-tls-setup.md	Db2 TLS 有効化の手順書
docs/claude-code-integration.md	サーバーを Claude Code やその他のエージェントに登録する方法、内部ゲートウェイの設定
docs/offline-build.md	ステージ A：ステージングマシンでのバンドル準備
docs/offline-deployment.md	ステージ B：エアギャップ環境内へのインストール（.deb、.pkg、.msi、バンドル、コンテナー）
docs/offline-upgrade-rollback.md	アップグレードとロールバック
docs/site-upgrade-runbook.md	サイトのアップグレード手順と、このリリースでの動作変更（USB メモリには UPGRADE-README.md として収録）
docs/acceptance-tests.md	リリース判定条件とその実行方法
docs/mock-environment.md	実証用に使われるローカルのモックデータベース
docs/adding-connectors.md	エンジンアダプターの追加方法
docs/troubleshooting.md	よくある障害と doctor の出力
IMPLEMENTATION_STATUS.md	実装済み／検証済み／未解決の項目一覧
SECURITY.md	脆弱性の報告方法、サポート対象バージョン、エアギャップ環境のサイトに修正を届ける方法
site/index.html	.github/workflows/pages.yml によって公開される製品のランディングページ（tests/unit/test_landing_page.py は、ページに表示される各ガード判定を再実行します）

脆弱性の報告

セキュリティ上の問題は、公開イシューではなく、GitHub の非公開脆弱性報告を通じて非公開で報告してください。SECURITY.md に、報告に含める内容とエアギャップ環境のサイトに修正を届ける方法を記載しています。このプロジェクトは universal-db-mcp のメンテナーが保守しており、メールアドレスを公開していません。Debian の要件により .deb の Maintainer フィールドに記載されているアドレスは、予約済みの .invalid ドメイン配下のプレースホルダーであり、誰にも届きません。

ライセンス

Apache-2.0 です。LICENSE と NOTICE を参照してください。どちらも wheel とオフラインバンドルの licenses/ ディレクトリに収録されています。.deb では、NOTICE とともに配置される DEP-5 の /usr/share/doc/universal-db-mcp/copyright ファイルにライセンスが記載されています。サードパーティーのコンポーネントには、それぞれ独自のライセンスが適用されます。バンドルでは sbom/cyclonedx.json に一覧が記載され、wheelhouse/ 内の各 wheel にはライセンスファイルが含まれています。

Db2 コネクターの ibm_db wheel には IBM Data Server Driver for ODBC と CLI の再配布可能ファイルが含まれており、IBM はアプリケーションの一部として配布することを許諾しています。これらは変更されておらず、適用される IBM のライセンスファイルおよび通知ファイルとともに収録されています（NOTICE を参照）。Db2 と IBM は International Business Machines Corporation の商標であり、ここではデータベースとそのドライバーの名称としてのみ使用しています。Microsoft の ODBC Driver for SQL Server と Oracle の Instant Client は再配布していません。各サイトでベンダーからインストールしてください。