safedb-mcp

SafeDB MCP

SafeDB MCP は、厳格な読み取り専用のガードレールを備え、AI エージェントが Postgres、MySQL、MariaDB、SQLite を調査およびクエリできる、安全な Model Context Protocol サーバーです。エージェントに本番環境の無制限な認証情報を渡すことなく、便利なデータベースアクセスを実現したいチーム向けに設計されています。

エージェントにデータベースの認証情報を直接渡すのは危険です。誤ったプロンプト、ツール呼び出し、生成された SQL ステートメントが 1 つあるだけで、データの変更、機密列の流出、高コストなクエリの実行につながる可能性があります。SafeDB MCP は、エージェントとデータベースの間にポリシーレイヤーを設けます。設定されたスキーマとテーブルのみを表示し、SQL は実行前に解析および検証され、行数には上限が設けられ、結果はマスキングされ、すべてのクエリ試行が監査されます。

このプロジェクトは MVP です。安全でないアクセスを許すよりも、誤検知やクエリのブロックを優先しており、完璧な SQL セキュリティを保証するものではありません。

機能

• MCP ツール：list_schemas、list_tables、describe_table、run_readonly_query、explain_query、get_safedb_policy
• pg による Postgres のサポート
• mysql2 による MySQL および MariaDB のサポート
• sql.js による SQLite ファイルのサポート
• 環境変数の展開に対応した YAML または JSON 設定
• SELECT、WITH ... SELECT、UNION、EXPLAIN SELECT に対応する AST ベースの読み取り専用 SQL ガードレール
• 結合、CTE、入れ子のサブクエリ、エイリアス、UNION を通じたテーブル検出
• エイリアスや式を通じて選択されたマスキング対象フィールドをブロックする列選択チェック
• 設定可能なテーブルの許可リスト、拒否リスト、行数制限、ステートメントのタイムアウト
• PII のマスキング：redact、email、partial、決定論的な hash
• 生の結果データを含まない JSONL 監査ログ
• CLI バイナリ：safedb-mcp
• TypeScript、Vitest、ESLint、Prettier

クイックスタート

npx @safedb/safedb-mcp init --output safedb.yaml
DATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp validate-config --config safedb.yaml
DATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp test-connection --config safedb.yaml
DATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp --config safedb.yaml

読み取り専用権限を持つ専用のデータベースロールを使用してください。SafeDB MCP は多層防御の一部であり、最小権限のデータベース認証情報に代わるものではありません。

Docker

Docker イメージには SafeDB MCP と Node.js および本番環境用の依存関係が含まれているため、Docker を利用できるホストであればどこでも同じように実行できます。

イメージをローカルでビルドします：

docker build -t safedb-mcp .

設定ファイルをマウントして MCP サーバーを実行します：

docker run --rm -i \
  -e DATABASE_URL=postgres://readonly:[email protected]:5432/app \
  -v "$PWD/safedb.yaml:/config/safedb.yaml:ro" \
  safedb-mcp

イメージ名の後に CLI コマンドを渡します：

docker run --rm \
  -e DATABASE_URL=postgres://readonly:[email protected]:5432/app \
  -v "$PWD/safedb.yaml:/config/safedb.yaml:ro" \
  safedb-mcp --config /config/safedb.yaml validate-config

設定例

database:
  type: postgres
  url: ${DATABASE_URL}

safety:
  default_limit: 100
  max_limit: 1000
  statement_timeout_ms: 5000
  allow_explain: true

access:
  schemas:
    public:
      allow_tables:
        - users
        - orders
        - products
      deny_tables:
        - secrets
      column_masks:
        users.email: email
        users.phone: partial
        users.password_hash: redact
        users.ssn: redact

audit:
  path: safedb-audit.jsonl

MySQL または MariaDB の場合は、database.type を設定し、データベース名をアクセススキーマとして使用します：

database:
  type: mysql
  url: ${DATABASE_URL}

access:
  schemas:
    app:
      allow_tables:
        - users
        - orders
      deny_tables:
        - secrets

SQLite の場合は、database.type を sqlite に設定し、database.path に .db ファイルを指定して、アクセススキーマとして main を使用します：

database:
  type: sqlite
  path: ./app.db

access:
  schemas:
    main:
      allow_tables:
        - users
        - orders
      deny_tables:
        - secrets

MCP クライアントの設定

Claude Desktop：

{
  "mcpServers": {
    "safedb": {
      "command": "safedb-mcp",
      "args": ["--config", "/absolute/path/to/safedb.yaml"],
      "env": {
        "DATABASE_URL": "postgres://readonly:password@localhost:5432/app"
      }
    }
  }
}

Cursor または Hermes 形式の MCP 設定：

{
  "servers": {
    "safedb": {
      "command": "safedb-mcp",
      "args": ["--config", "/absolute/path/to/safedb.yaml"],
      "env": {
        "DATABASE_URL": "postgres://readonly:password@localhost:5432/app"
      }
    }
  }
}

セキュリティ保証

SafeDB MCP は、以下の保証を目指しています：

• MCP ツールを通じて調査またはクエリできるのは、設定されたスキーマとテーブルのみです。
• SQL は実行前に解析され、データを変更するステートメントの種類や複数のステートメントはブロックされます。
• テーブルのアクセスポリシーは、結合、CTE、入れ子のサブクエリ、エイリアス、UNION を通じて検出された実際のテーブルに対して確認されます。
• マスキング対象の列は、レスポンスのマスキングを回避するようなエイリアスや式を通じて選択できません。
• ドライバーが対応している場合、クエリはローカルのステートメントタイムアウトを設定した読み取り専用トランザクション内で実行されます。
• 返される行数は、外側の LIMIT によって制限されます。
• 設定された PII フィールドは、ツールのレスポンスを返す前にマスキングされます。
• 監査ログには、試行、判断、検出されたテーブル、行数、処理時間が記録されますが、生の結果行は記録されません。
• パスワードやシークレットが意図的にログに記録されることはありません。

対象外

• クエリの安全性に関する形式的な証明。
• 有効な方言固有の読み取り専用 SQL 構文すべてへの対応。
• 書き込み操作、マイグレーション、ストアドプロシージャの実行、または COPY。

開発

npm install
npm run build
npm test
npm run lint

ロードマップ

• ツールごとおよびテーブルごとのレート制限。
• オプションの OpenTelemetry トレース。
• 署名付き監査ログ。
• 公開済み Docker イメージおよび Helm チャート。

ライセンス

MIT