universal-db-mcp

Universal Database MCP Server

AI エージェントからデータベースにアクセスするための、セキュリティを最優先した Python ネイティブの MCP サーバーです。

---

開発の背景

ほとんどのデータベース MCP サーバーは、AI エージェントに生の SQL アクセスを許可し、問題が起きないことを期待します。 このサーバーでは、LLM からの入力を信頼できないものとみなし、クエリがデータベースに到達する前に 8 層のインジェクション防止策を適用します。UNION 攻撃、ステートメントの連結、時間ベースのインジェクション、コメントによる回避もブロックします。

対応：PostgreSQL · SQLite · MySQL · DuckDB（カラム型分析）

---

セットアップ不要：今すぐお使いのノート PC で動作します

Docker もクラウドアカウントも、インストールするデータベースサーバーも不要です。DuckDB と SQLite はプロセス内で動作します。

# Query a local SQLite database — one command, zero infra
SQLITE_PATH=./myapp.db uvx universal-db-mcp

# Query a local DuckDB file or parquet files
DUCKDB_PATH=./analytics.duckdb uvx universal-db-mcp

# In-memory DuckDB for throwaway analysis
DUCKDB_PATH=:memory: uvx universal-db-mcp

Claude Code の ~/.claude/mcp_servers.json、または Claude Desktop の ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）／ %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "mydb": {
      "command": "uvx",
      "args": ["universal-db-mcp"],
      "env": {
        "SQLITE_PATH": "/Users/you/projects/myapp/db.sqlite3",
        "ALLOW_DESTRUCTIVE": "false"
      }
    }
  }
}

保存後に Claude Desktop／Claude Code を再起動すれば完了です。

これで完了です。Claude Code がツールを自動的に検出します。

その他のクライアント設定（Claude Desktop、Cursor、Windsurf、Docker）は examples/ にあります。

---

セキュリティモデル：8 層

デフォルトは読み取り専用です。多層防御を採用しています。すべてのクエリはドライバーに渡る前に検証されます。

層	内容
1	ドライバーレベルの読み取り専用 — PostgreSQL のセッションフラグ、SQLite の mode=ro URI、DuckDB の read_only=True。SQL の解析前に書き込みを拒否します。
2	キーワードのブロック — 読み取り専用モードでは DROP、DELETE、TRUNCATE、ALTER、INSERT、UPDATE、GRANT、EXEC をブロックします
3	インジェクションパターンの検出 — UNION SELECT、ステートメントの連結、SQL コメント（--、/*）、xp_、SLEEP()、WAITFOR、BENCHMARK()
4	複数ステートメントの拒否 — ステートメントを区切る ; は常にブロックされます
5	パラメーター型の強制 — パラメーターとして受け付けるのは str、int、float、bool、null のみです
6	結果サイズの制限 — メモリ枯渇を防ぐため、MAX_RESULT_ROWS（デフォルトは 1000）で切り詰めます
7	識別子のサニタイズ — 内部で生成される SQL では、テーブル名／カラム名からメタ文字を除去します
8	DuckDB のファイルシステムブロックリスト — アダプター層で read_csv()、read_parquet()、glob()、LOAD、INSTALL、httpfs、COPY をブロックします。read_only=True でブロックされるのは書き込みのみで、ファイルの読み取りはブロックされません

脅威モデルの詳細：docs/SECURITY.md

---

DuckDB：インフラ不要の分析

DuckDB はプロセス内で動作し（サーバー不要）、Parquet、CSV、JSON をネイティブに読み取ります。 ウェアハウスを立ち上げずに、AI エージェントを分析データに接続できます。

# Query parquet files directly
DUCKDB_PATH=:memory: uvx universal-db-mcp

次に、Claude Code で次を実行します。

You: "Load sales.parquet and show me monthly revenue by region"
Claude: [uses query tool → SELECT region, strftime('%Y-%m', date) AS month, SUM(revenue) ...]

---

自然言語 → SQL

NL-to-SQL 専用ツールは不要です。Claude はすでにこれを実行できます。schema ツールを渡し、平易な英語で尋ねてください。

You: "Which customers placed more than 5 orders last month?"
Claude: [calls schema() to see table structure, then query() with the
         generated SQL — every query still passes through all 8 security
         layers before touching your database]

試作中は dry_run: true（DRYRUN=true）と組み合わせてください。Claude は何も実行せずにクエリプランを受け取れます。

---

Docker

docker build -t universal-db-mcp .
docker run -i --rm \
  -e POSTGRES_URI=postgresql://readonly:[email protected]:5432/mydb \
  -e ALLOW_DESTRUCTIVE=false \
  universal-db-mcp

MCP クライアントへの組み込み方法については、examples/docker_mcp_config.json をご覧ください。

---

すべてのデータベース

# PostgreSQL
POSTGRES_URI=postgresql://readonly:pass@localhost/mydb uvx universal-db-mcp

# SQLite (local file, zero infra)
SQLITE_PATH=./db.sqlite3 uvx universal-db-mcp

# MySQL
MYSQL_URI=mysql://readonly:pass@localhost/mydb uvx universal-db-mcp

# DuckDB (columnar, in-process analytics)
DUCKDB_PATH=./analytics.duckdb uvx universal-db-mcp

# Multiple databases simultaneously
POSTGRES_URI=... SQLITE_PATH=... uvx universal-db-mcp

---

MCP ツール

ツール	説明
query	SQL を実行します — デフォルトでは読み取り専用で、8 層すべてのセキュリティ対策が適用されます
schema	テーブルとカラムを確認します — 設定は不要です
explain	クエリを実行せずに、クエリの実行計画を取得します
health	接続状態、DB バージョン、接続プールのメトリクスを確認します
list_databases	設定済みのすべてのデータベースと接続状態を表示します
query_history	直近 100 件の実行済みクエリを確認します
snapshot_schema	スキーマの差分検出用に現在のスキーマを記録します
schema_diff	現在のスキーマと直近のスナップショットを比較します

v1.1.0：ドライランモード（DRYRUN=true）、テーブルの許可リスト（WHITELISTED_TABLES）、クエリの複雑さに関する警告、構造化された監査ログ、接続検証用の --check CLI フラグに対応しました。CHANGELOG.md を参照してください。

---

設定

# ── PostgreSQL ─────────────────────────────────────
POSTGRES_URI=postgresql://user:pass@host:5432/db
POSTGRES_READONLY=true          # default: true

# ── SQLite ─────────────────────────────────────────
SQLITE_PATH=/path/to/database.db
SQLITE_READONLY=true            # default: true

# ── MySQL ──────────────────────────────────────────
MYSQL_URI=mysql://user:pass@host:3306/db
MYSQL_READONLY=true             # default: true

# ── DuckDB ─────────────────────────────────────────
DUCKDB_PATH=/path/to/analytics.duckdb   # or :memory:
DUCKDB_READONLY=true            # default: true

# ── Security ───────────────────────────────────────
ALLOW_DESTRUCTIVE=false         # default: false — blocks INSERT/UPDATE/DELETE/DROP
MAX_RESULT_ROWS=1000            # truncate large results
ENABLE_LOGGING=true             # log queries to stderr
QUERY_TIMEOUT=30                # seconds
RATE_LIMIT_RPM=60               # requests per minute

---

セキュアなデータベースユーザー

必ず読み取り専用の専用アカウントを使用してください。MCP サーバーに、データを変更できる認証情報を決して与えないでください。

PostgreSQL：

CREATE USER mcp_agent WITH PASSWORD 'strong_random_password';
GRANT CONNECT ON DATABASE mydb TO mcp_agent;
GRANT USAGE ON SCHEMA public TO mcp_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_agent;

MySQL：

CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'strong_random_password';
GRANT SELECT ON mydb.* TO 'mcp_agent'@'localhost';
FLUSH PRIVILEGES;

---

開発

git clone <repo-url>
cd universal-db-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests (67+ passing, no external DB required for SQLite + DuckDB)
pytest

# Security tests only
pytest tests/test_security.py -v

# With coverage
pytest --cov=src/universal_db_mcp --cov-report=term-missing

---

アーキテクチャ

src/universal_db_mcp/
├── server.py          # FastMCP server — 5 tools
├── config.py          # Env-var config via Pydantic
├── adapters/
│   ├── base.py        # Abstract adapter + result dataclasses
│   ├── postgresql.py  # asyncpg, connection pool, read-only via init callback
│   ├── sqlite.py      # aiosqlite, read-only via file URI mode=ro
│   ├── mysql.py       # aiomysql, DictCursor
│   └── duckdb.py      # duckdb, thread-pool executor, lock-guarded
└── security/
    └── sanitizer.py   # SQLSanitizer — 8-layer injection prevention

docs/
└── SECURITY.md        # Full security architecture and threat model

---

Google MCP Toolbox との比較

	このプロジェクト	Google MCP Toolbox
ランタイム	Python — pip install / uvx	Go バイナリ / Docker
ローカル DB	SQLite + DuckDB（インフラ不要）	SQLite なし
分析	DuckDB（プロセス内）	列指向アダプターなし
認証モデル	デフォルトで読み取り専用 + 環境変数	IAM / GCP ネイティブ
SQL インジェクション	8 層のサニタイザー + パラメーター化	認証重視
拡張	Python エコシステム、任意の pip パッケージ	Go プラグイン
ベンダー	中立	Google Cloud への誘導

ツールによって適した用途は異なります。クラウド依存なしで、Python ネイティブかつローカル優先の、セキュリティを強化したアクセスが必要な場合にご利用ください。

---

ライセンス

MIT — LICENSE

---

セキュリティに関する注意：このサーバーは AI エージェントにデータベースへのアクセスを提供します。必ず読み取り専用の認証情報を使用し、本番環境にデプロイする前に docs/SECURITY.md を確認してください。また、.env ファイルを決してコミットしないでください。