Skip to main content
Glama
secure-mcp-database-crud

secure-mcp-database-crud

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

Related MCP server: Task Manager MCP Server

公開する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後に再起動します。

Available Tools

6 tools
confirm_delete_taskA
Destructive

Delete the confirmed task after validating its signed, single-use token.

Inputs: task_id (required), confirmation_token (required). Returns: object

create_taskA

Create one validated task and its audit event atomically.

Inputs: title (required), status, due_date, description. Returns: object

get_taskA
Read-onlyIdempotent

Get one task by its positive integer ID.

Inputs: task_id (required). Returns: object

list_tasksB
Read-onlyIdempotent

List tasks with bounded pagination and allowlisted sorting.

Inputs: limit, offset, status, sort_by, +1 more. Returns: object

prepare_delete_taskA
Read-onlyIdempotent

Return the exact delete target and a short-lived confirmation token.

Inputs: task_id (required). Returns: object

update_taskA
Destructive

Update only allowlisted task fields, optionally checking the observed version.

Inputs: task_id (required), title, status, due_date, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct operation: create, get, list, update, and a two-step delete with prepare and confirm. There is no functional overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., create_task, update_task, prepare_delete_task). The naming is clear and predictable.

    Tool Count5/5

    With 6 tools, the server is well-scoped for task CRUD operations. The count is neither excessive nor insufficient for the domain.

    Completeness5/5

    The tool set covers full CRUD functionality plus a secure two-step delete. No obvious missing operations for the stated purpose of secure task management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables task management through a local MySQL database, supporting full CRUD operations and automated tracking of status transitions. Users can create, search, and update tasks while maintaining a detailed progress history for all activities.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A security-focused Model Context Protocol server for task management over stdio, backed by SQLite. It exposes tools to create, list, complete, delete, and search tasks with strict validation, parameterized SQL, confirmation for deletes, and full audit logging.
      16 npm
      MIT