Secure MCP Database CRUD

English | 日本語

SQLiteまたはMySQLへ接続し、安全なタスクCRUDだけを公開するMCPサーバーです。 任意SQLを公開せず、入力検証、パラメータ化クエリ、最小権限、監査イベント、 トランザクション、署名付き削除確認を一つの実行可能なサンプルにまとめています。

このリポジトリは記事 「データベースに接続するMCPサーバー：SQLiteとMySQLで安全なCRUD Toolを作る」 の完成形コードです。

5分で試す（SQLite）

前提は uv のみです。uvがPython 3.12も用意します。

git clone https://github.com/yunosuke-github/secure-mcp-database-crud.git
cd secure-mcp-database-crud
cp .env.example .env
uv sync
uv run mcp-db-init
uv run mcp-database-crud

最後のコマンドはstdioで待機します。これは正常です。MCPクライアントには次のように登録します。 /absolute/path/... は実際の絶対パスへ置き換えてください。

{
  "mcpServers": {
    "secure-task-database": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/secure-mcp-database-crud",
        "run",
        "mcp-database-crud"
      ]
    }
  }
}

動作をすぐ確認する場合はテストを実行します。

uv run pytest

公開するTool

Tool	種別	役割
list_tasks	読み取り	ステータス、件数、オフセット、許可済みソートで一覧取得
get_task	読み取り	IDで1件取得。不存在も正常な結果として返す
create_task	更新	タスクとcreated監査イベントを同時に作成
update_task	更新	許可済み項目だけを更新し、必要なら楽観ロックを適用
prepare_delete_task	読み取り	対象と短時間有効な署名済みトークンを返す
confirm_delete_task	破壊的操作	対象・版・期限・nonceを検証して削除

execute_sqlのようなToolはありません。モデルが選べるのは用途が限定された操作だけです。

MySQLで動かす

Docker ComposeはMySQL 8.4、スキーマ、読み取り専用ユーザー、更新専用ユーザーを用意します。

cp .env.example .env
# .env の DATABASE_BACKEND を mysql へ変更
docker compose up -d --wait mysql
uv run mcp-database-crud

ローカル用パスワードは公開されたデモ値です。本番では必ず変更してください。アプリケーションの ユーザーにはDDL権限がないため、MySQLのスキーマ作成は起動時処理から分離しています。

MySQL統合テストはサービス起動後に明示的に実行します。

RUN_MYSQL_TESTS=1 uv run pytest -m mysql
docker compose down

安全性の境界

flowchart LR
    U[ユーザー] --> C[AIクライアント]
    C -->|Tool名と構造化引数| M[MCPサーバー]
    M --> V[Pydantic検証]
    V --> R[TaskRepository]
    R -->|固定SQLとバインド値| D[(SQLite / MySQL)]
    M -.->|SQL・認証情報は返さない| C

• 値はすべてプレースホルダーへバインドします。
• ソート列と方向はEnumから固定SQL断片へ変換します。
• SQLiteの読み取りはmode=roとquery_onlyを併用します。
• MySQLはreader/writerのユーザーと接続プールを分けます。
• タスク更新とtask_events追加は同じトランザクションです。
• 更新時は取得したupdated_atをWHERE条件へ含めます。
• 削除トークンはHMAC署名され、操作、ID、版、有効期限、nonceへ結び付きます。
• 成功済みnonceのハッシュを削除トランザクション内で一意保存し、再利用を拒否します。
• ToolエラーにはSQL、ファイルパス、ホスト名、認証情報を含めません。

ディレクトリ構成

src/mcp_database_crud/
├── config.py                    # 環境変数とSecretStr設定
├── confirmation.py              # HMAC確認トークン
├── models.py                    # Toolの入力・出力Schema
├── server.py                    # FastMCPの組み立てとstdio起動
├── database/
│   ├── protocol.py              # SQLite/MySQL共通契約
│   ├── sqlite_repository.py     # 呼び出し単位の接続とトランザクション
│   ├── mysql_repository.py      # reader/writer接続プール
│   └── sqlite_schema.sql
└── tools/
    ├── handlers.py              # 安全な結果とエラー変換
    ├── read_tools.py            # 読み取りTool登録
    └── write_tools.py           # 更新・削除Tool登録
docker/mysql/init/001_schema.sql # MySQLスキーマと最小権限GRANT
tests/                            # セキュリティ特性とRepository契約

設定

.env.exampleを.envへコピーして使います。.envはGit管理対象外です。

変数	用途	既定値
DATABASE_BACKEND	sqliteまたはmysql	sqlite
SQLITE_PATH	SQLiteファイル	data/tasks.db
CONFIRMATION_SIGNING_KEY	削除トークンのHMAC鍵（32文字以上）	必須
CONFIRMATION_TTL_SECONDS	削除確認の有効秒数	120
MYSQL_*	ホスト、DB、reader/writer認証情報	ローカルCompose用
MYSQL_POOL_SIZE	reader/writer各プールの接続数	5
DB_TIMEOUT_SECONDS	DB接続・SQLiteロック待機秒数	5

安全な署名鍵は、例えば次のように生成できます。

python -c 'import secrets; print(secrets.token_urlsafe(48))'

開発

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest --cov=mcp_database_crud --cov-report=term-missing

テストでは、SQLインジェクション風文字列がデータとして保存されること、監査INSERT失敗時に 更新が戻ること、読み取り専用SQLiteが書き込みを拒否すること、改変・期限切れ・別タスク用・ 古い版・再利用トークンが拒否されることを確認します。

本番導入前の注意

このサンプルはローカルstdioサーバーを対象としています。リモート公開する場合は、Tool入力の user_idを信用せず、認証コンテキストから主体を取得して各タスクへの認可を追加してください。 既存の業務APIが認可、通知、イベント発行を担っているなら、DBへ直接接続せずAPI経由を優先します。 レート制限、監視、バックアップ、マイグレーション、シークレット管理も環境に合わせて追加してください。

トラブルシューティング

• unable to open database file: uv run mcp-db-initを先に実行してください。
• confirmation_signing_keyの検証エラー: .envを作り、32文字以上の鍵を設定してください。
• MySQLへ接続できない: docker compose psでmysqlがhealthyか確認してください。
• MySQLスキーマを作り直したい: このComposeはtmpfsです。docker compose down後に再起動します。