mcp-encrypted-sqlite

暗号化 SQLite MCP サーバー

暗号化 SQLite データベース用の MCP サーバー

SQLCipher を使用して暗号化 SQLite データベースを操作するための Model Context Protocol（MCP）サーバーです。このサーバーは、暗号化 SQLite データベースの構造の読み取り、テーブルへのクエリの実行、CRUD 操作を行うツールを提供します。

すべての MCP クライアントに対応（Cursor、Claude Desktop など）。

以下のアプリケーションの暗号化データベースで動作します： MoneyMoney、1Password、Signal、WhatsApp、Firefox、Telegram、KeePass など、SQLCipher 暗号化を使用するアプリケーション。

機能

• 暗号化 SQLite のサポート：SQLCipher 4 で暗号化されたデータベースで動作します。この MCP サーバーの最大の特長です
• 暗号化されたパスフレーズ：macOS Keychain との連携による AES-256-GCM 暗号化パスフレーズのサポート
• データベースの調査：テーブル、カラム、インデックス、スキーマのメタデータを一覧表示します
• クエリのサポート：任意の SQL クエリを実行します（SELECT、INSERT、UPDATE、DELETE、DDL）
• CRUD 操作：フィルタリングを使用して行の挿入、更新、削除を行います
• 設定可能な暗号プロファイル：さまざまな SQLCipher 設定に対応します
• MCP プロトコル：STDIO を介した Model Context Protocol の完全な実装
• セキュリティ：SQL インジェクションを防ぐ SQL 識別子の検証
• デバッグモード：MCP_DEBUG 環境変数による任意のデバッグ出力
• 入力検証：上限、オフセット、識別子を包括的に検証します

暗号化 SQLite を使う理由

多くの人気アプリケーションでは、機密データを保護するために暗号化 SQLite データベース（SQLCipher）が使用されています。この MCP サーバーは、こうした暗号化データベースを扱うために特別に設計されています。

暗号化 SQLite データベースを使用するアプリケーション

• MoneyMoney（macOS）：ローカルデータベースを暗号化する家計管理アプリ
• 1Password：ローカルの保管庫の保存に SQLCipher を使用するパスワードマネージャー
• Signal：SQLCipher で保護されたメッセージデータベースを使用する暗号化メッセージングアプリ
• WhatsApp：ローカルのメッセージ保存に暗号化 SQLite を使用するメッセージングアプリ
• Firefox：ログイン情報の暗号化データベースに SQLCipher を使用するブラウザー
• Telegram：ローカルのデータベース保存に暗号化を使用するメッセージングアプリ
• KeePass：暗号化 SQLite データベースファイルに対応するパスワードマネージャー

これらのアプリケーションや、その他の SQLCipher で暗号化されたデータベースのデータにアクセスする場合、この MCP サーバーが必要なツールを提供します。暗号化データベースのパスフレーズが必要です。

要件

• Java 21 以上（JDK）
• Gradle（ラッパーが含まれています）
• 暗号化に対応した SQLite JDBC ドライバー（sqlite-jdbc-crypt の sqlite-jdbc-3.50.1.0.jar）

クイックスタート

Cursor（ワンクリックインストール）

Cursor にこの MCP サーバーをインストールする最も簡単な方法は、Cursor MCP Store を利用することです。

1. cursor.store/mcp/rosch100/mcp-encrypted-sqlite にアクセスします
2. **「Add to Cursor」**をクリックします
3. 案内に従ってデータベースのパスとパスフレーズを設定します

その他の MCP クライアント

このサーバーは、MCP に対応するすべてのクライアントで動作します。セットアップ手順については、以下の設定セクションを参照してください。

インストール

Docker（推奨）

GitHub Container Registry のビルド済み Docker イメージを使用します。

docker pull ghcr.io/rosch100/mcp-encrypted-sqlite:latest

クイックスタート： Docker Desktop のセットアップについては、DOCKER_QUICKSTART.md を参照してください。

詳細な設定： 高度なオプションについては、DOCKER_CONFIGURATION.md を参照してください。

ソースからのビルド

1. リポジトリをクローンします：

   git clone https://github.com/rosch100/mcp-encrypted-sqlite.git

   cd mcp-encrypted-sqlite

2. プロジェクトをビルドします：

   ./gradlew build installDist

ビルドプロセスでは、sqlite-jdbc-crypt releases から sqlite-jdbc-3.50.1.0.jar が自動的にダウンロードされ、libs/ ディレクトリに配置されます。

実行ファイルは build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite に生成されます。

設定

この MCP サーバーは、あらゆる MCP 互換クライアント（Cursor、Claude Desktop など）で動作します。設定形式は Model Context Protocol specification に準拠しています。

サーバーは STDIO（標準入出力）経由で通信します。以下の設定を MCP クライアントの設定ファイルに追加してください。

設定ファイルの場所：

• Cursor：~/.cursor/mcp.json
• Claude Desktop（macOS）：~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop（Windows）：%APPDATA%\Claude\claude_desktop_config.json
• その他のクライアント：クライアントのドキュメントを参照してください

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"your-passphrase\"}"
      ]
    }
  }
}

オプションのパラメーター：

• transport：デフォルトは "stdio" です（省略可能）
• cwd：絶対パスを使用する場合は不要です（省略可能）
• immutable：--args JSON 内で指定するオプションのブール値です。true の場合、SQLite URI file:…?immutable=1 を使って DB を開きます（ファイルロックなし）。別のアプリ（例：MoneyMoney）によって排他的にロックされている DB を参照する場合に使用します。このモードでは、すべての書き込みツール／SQL が無効になります（insert_or_update／delete_rows は省略され、execute_sql は読み取り専用のステートメントのみ受け付けます）。
• env：Java がシステムの PATH にない場合、またはカスタム Java インストールを使用する場合にのみ必要です：

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"your-passphrase\"}"
      ],
      "env": {
        "JAVA_HOME": "/path/to/java/home"
      }
    }
  }
}

Docker の設定

プレーンテキストのパスフレーズ

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/database.sqlite:/data/database.sqlite:ro",
        "ghcr.io/rosch100/mcp-encrypted-sqlite:latest",
        "--args",
        "{\"db_path\":\"/data/database.sqlite\",\"passphrase\":\"your-passphrase\"}"
      ]
    }
  }
}

暗号化されたパスフレーズ（推奨）

暗号化されたパスフレーズを使用する場合は、暗号化キーを環境変数として渡す必要があります：

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_SQLITE_ENCRYPTION_KEY=your-encryption-key",
        "-v", "/path/to/your/database.sqlite:/data/database.sqlite:ro",
        "ghcr.io/rosch100/mcp-encrypted-sqlite:latest",
        "--args",
        "{\"db_path\":\"/data/database.sqlite\",\"passphrase\":\"encrypted:your-encrypted-passphrase\"}"
      ]
    }
  }
}

重要な注意事項：

• -e フラグは -v フラグの前に指定する必要があります
• macOS Keychain は Docker コンテナからアクセスできません。暗号化キーを明示的に渡してください
• 暗号化キーを取得するには、次を実行します：security find-generic-password -s "mcp-encrypted-sqlite" -a "encryption-key" -w
• データベースファイルはデフォルトで読み取り専用（:ro）としてマウントされます。書き込みアクセスが必要な場合は :ro を削除してください

**セキュリティに関する警告：**設定ファイルに暗号化キーと暗号化されたパスフレーズの両方をプレーンテキストで保存することは、セキュリティ上のリスクです。安全な代替手段については、DOCKER_CONFIGURATION.md を参照してください。

カスタム暗号プロファイル

設定 JSON に cipherProfile を含めると、デフォルトの SQLCipher 4 設定を上書きできます：

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"your-passphrase\",\"cipherProfile\":{\"name\":\"SQLCipher 4 defaults\",\"pageSize\":4096,\"kdfIterations\":256000,\"hmacAlgorithm\":\"HMAC_SHA512\",\"kdfAlgorithm\":\"PBKDF2_HMAC_SHA512\"}}"
      ]
    }
  }
}

注：cipherProfile のすべてのフィールドはオプションです。デフォルト設定から上書きしたい項目のみ指定してください。個々のツール呼び出しでも cipherProfile を指定できますが、一貫性を保つため、MCP サーバーの設定で一度指定することをおすすめします。

暗号化されたパスフレーズ

セキュリティを強化するため、パスフレーズを暗号化して保存できます。サーバーはAES-256-GCM 暗号化を使用します。認証付き暗号化を提供し、安全かつ高速です。

macOS Keychain（macOS での使用を推奨）

1. キーを生成して Keychain に保存します： 次を実行します：./store-key-in-keychain.sh --generate

2. パスフレーズを暗号化します： 次を実行します：./encrypt-passphrase.sh "your-plain-passphrase"

環境変数が設定されていない場合、キーは Keychain から自動的に読み込まれます。

メリット：

• キーは macOS によって安全に暗号化され、保存されます
• 環境変数は不要です
• macOS ユーザーのパスワードで自動的にロックが解除されます
• すべてのアプリケーションでシステム全体にわたって使用できます

環境変数（クロスプラットフォーム）

1. 暗号化キーを生成します： 次を実行します：java -cp build/libs/mcp-encrypted-sqlite-VERSION.jar com.example.mcp.sqlite.config.PassphraseEncryption

2. 暗号化キーを設定します： 次を実行します：export MCP_SQLITE_ENCRYPTION_KEY="<your-generated-key>"

3. パスフレーズを暗号化します： 次を実行します：java -cp build/libs/mcp-encrypted-sqlite-VERSION.jar com.example.mcp.sqlite.util.EncryptPassphrase "your-plain-passphrase"

使用方法

暗号化されたパスフレーズ（encrypted: 接頭辞付き）を設定に使用します：

Keychain を使用する macOS の場合（推奨）：

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"encrypted:<encrypted-passphrase>\"}"
      ]
    }
  }
}

注：env セクションは不要です。キーは macOS Keychain から自動的に読み込まれます。

環境変数を使用する場合（クロスプラットフォーム）：

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"encrypted:<encrypted-passphrase>\"}"
      ],
      "env": {
        "MCP_SQLITE_ENCRYPTION_KEY": "<your-encryption-key>"
      }
    }
  }
}

セキュリティに関する重要な注意事項：

• 暗号化キーを必ず利用可能な状態にしてください（macOS Keychain または MCP_SQLITE_ENCRYPTION_KEY 環境変数）
• サーバーは暗号化されたパスフレーズ（encrypted: で始まるもの）を自動的に検出し、復号します
• 強力なキーを生成するには、PassphraseEncryption.generateKey() を使用してください（256 ビット／32 バイト）
• AES-256-GCM は認証付き暗号化を提供します
• 弱いキーは自動的に拒否されます

利用可能なツール

list_tables

データベース内のすべてのテーブルを一覧表示します。デフォルトではテーブル名のみを表示し、include_columns=true の場合は列の詳細も表示します。

パラメーター：

• db_path（設定済みの場合は省略可）：データベースファイルへのパス
• passphrase（設定済みの場合は省略可）：データベースのパスフレーズ
• include_columns（省略可、デフォルト：false）：true の場合、列の詳細も返されます

例：

{
  "name": "list_tables",
  "arguments": {
    "include_columns": true
  }
}

get_table_data

任意のフィルタリング、列選択、ページネーションを指定して、テーブルからデータを読み取ります。

パラメーター：

• table（必須）：テーブル名
• columns（省略可）：選択する列名の配列
• filters（省略可）：フィルタリングに使用する列と値のペアを含むオブジェクト
• limit（省略可、デフォルト：200）：最大行数
• offset（省略可、デフォルト：0）：ページネーションのオフセット

例：

{
  "name": "get_table_data",
  "arguments": {
    "table": "accounts",
    "columns": ["id", "name", "balance"],
    "filters": {"status": "active"},
    "limit": 50,
    "offset": 0
  }
}

execute_sql

任意の SQL 文（SELECT、INSERT、UPDATE、DELETE、DDL）を実行します。

セキュリティ警告：このツールはパラメーター化を行わずに生の SQL を実行します。信頼できる SQL のみを使用するか、このツールを呼び出す前に適切な検証とサニタイズが実施されていることを確認してください。より安全に操作するには、パラメーター化クエリを使用する他のツール（get_table_data、insert_or_update、delete_rows）を使用してください。

パラメーター：

• sql（必須）：実行する SQL 文

例：

{
  "name": "execute_sql",
  "arguments": {
    "sql": "SELECT COUNT(*) FROM transactions WHERE amount > 1000"
  }
}

insert_or_update

UPSERT 操作（競合時に INSERT または UPDATE）を実行します。

パラメーター：

• table（必須）：テーブル名
• primary_keys（必須）：主キー列名の配列
• rows（必須）：挿入または更新する行オブジェクトの配列

例：

{
  "name": "insert_or_update",
  "arguments": {
    "table": "accounts",
    "primary_keys": ["id"],
    "rows": [
      {"id": 1, "name": "Account 1", "balance": 1000.0},
      {"id": 2, "name": "Account 2", "balance": 2000.0}
    ]
  }
}

delete_rows

フィルターに基づいて、テーブルから行を削除します。

パラメーター：

• table（必須）：テーブル名
• filters（必須）：フィルタリングに使用する列と値のペアを含むオブジェクト

例：

{
  "name": "delete_rows",
  "arguments": {
    "table": "transactions",
    "filters": {"status": "cancelled"}
  }
}

get_table_schema

テーブルの詳細なスキーマ情報（列、インデックス、外部キー、制約）を取得します。

パラメーター：

• table（必須）：テーブル名

例：

{
  "name": "get_table_schema",
  "arguments": {
    "table": "accounts"
  }
}

list_indexes

テーブルのすべてのインデックスを一覧表示します。

パラメーター：

• table（必須）：テーブル名

例：

{
  "name": "list_indexes",
  "arguments": {
    "table": "accounts"
  }
}

デバッグモード

サーバーは、MCP_DEBUG 環境変数による任意のデバッグ出力に対応しています。有効にすると、詳細なデバッグ情報が stderr（MCP プロトコルの要件に準拠するため、stdout ではありません）に書き込まれます。

デバッグモードを有効にする：

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"your-passphrase\"}"
      ],
      "env": {
        "MCP_DEBUG": "true"
      }
    }
  }
}

デバッグ出力には次の情報が含まれます：

• サーバーの起動情報（Java のバージョン、OS、引数）
• 設定の解析の詳細
• リクエストの処理情報
• レスポンスのサイズと構造
• データベース接続の詳細

**注：**ログを見やすく保つため、デバッグ出力はデフォルトで無効になっています。問題のトラブルシューティングを行う場合にのみ有効にしてください。

デフォルトの暗号化プロファイル

サーバーはデフォルトで SQLCipher 4 のデフォルト設定を使用します。

• cipher_page_size: 4096
• kdf_iter: 256000
• cipher_hmac_algorithm: HMAC_SHA512
• cipher_kdf_algorithm: PBKDF2_HMAC_SHA512
• cipher_use_hmac: ON
• cipher_plaintext_header_size: 0

これらの設定は、「DB Browser for SQLite」などのツールで SQLCipher 4 を使用する際のデフォルト設定と一致します。

開発

開発環境のセットアップ、ビルド、テスト、プロジェクト構成については、DEVELOPMENT.md を参照してください。

セキュリティに関する考慮事項

一般的なセキュリティ

• パスフレーズ：パスフレーズはメモリ内にのみ保存され、ログに記録されることはありません
• 暗号化されたパスフレーズ：設定ファイルにパスフレーズを保存する場合は、AES-256-GCM で暗号化したパスフレーズを使用してください（暗号化されたパスフレーズセクションを参照）
• メモリ：復号されたパスフレーズは、Java の文字列（不変）としてメモリに残ることに注意してください。最大限のセキュリティを確保するには、char[] 配列の使用を検討してください。ただし、現在は実装されていません。
• トランスポート：サーバーにリモートからアクセスする場合は、安全なトランスポートチャネル（暗号化されたセッションなど）を使用してください
• ファイルのアクセス許可：データベースファイルに適切なファイルシステムのアクセス許可が設定されていることを確認してください

セキュリティのベストプラクティス

1. AES-256-GCM 暗号化による暗号化されたパスフレーズを使用する
2. PassphraseEncryption.generateKey() を使用して強力なキーを生成する（256 ビット／32 バイト）
3. 暗号化キーを安全に保管する：macOS では macOS キーチェーン（推奨）、または安全なシークレットストレージを使用する
4. 暗号化キーと暗号化されたパスフレーズを同じ設定ファイルに保存しない。ラッパースクリプトまたは環境変数を使ってキーを安全に読み込んでください（詳細は DOCKER_CONFIGURATION.md を参照）
5. キーを定期的にローテーションする。ローテーション時には、すべてのパスフレーズを新しいキーで再暗号化してください
6. 環境（開発、ステージング、本番）ごとに異なるキーを使用する
7. キーや暗号化されたパスフレーズをバージョン管理にコミットしない
8. シークレットを含む設定ファイルのファイルアクセス許可を制限する（chmod 600）

トラブルシューティング

MCP サーバーの通信問題のデバッグ

MCP サーバーには、通信の問題の診断に役立つ包括的なデバッグ機能が備わっています。

ログの確認

MCP クライアントの場合：

• クライアントのログ出力を確認してください（例：Cursor：出力パネル →「MCP Logs」）
• すべてのデバッグ出力は stderr に書き込まれます

手動テスト： 実行：./build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite --args '{"db_path":"/path/to/db.sqlite","passphrase":"secret"}' 2>&1 | tee mcp-debug.log

よくある通信の問題

1. サーバーが起動しない

• 症状：ログが表示されず、サーバーが応答しません
• デバッグ：起動ログを確認します：
  • Java のバージョンが記録されています
  • 引数が記録されています
  • 設定の解析結果が記録されています
• 解決策：
  • Java が正しくインストールされていることを確認します
  • MCP の設定（mcp.json）を確認します
  • command フィールドと args フィールドのパスを確認します

2. JSON の解析エラー

• 症状：ログに「Parse error」と表示されます
• デバッグ：サーバーには次の情報が記録されます：
  • 受信した JSON の先頭 500 文字
  • スタックトレース付きの正確な例外情報
• 解決策：
  • MCP の設定内の JSON 構造を確認します
  • JSON が適切にエスケープされていることを確認します
  • 必須フィールドがすべて含まれていることを確認します

3. 応答がない、または不正な応答

• 症状：リクエストに応答しない、またはタイムアウトが発生します
• デバッグ：サーバーには次の情報が記録されます：
  • ID とメソッドを含む、受信した各リクエスト
  • 応答のサイズとステータス
  • 書き込み後のフラッシュ状態
• 解決策：
  • STDOUT が利用可能かどうかを確認します（起動時に記録されます）
  • 応答サイズを確認します（非常に大きな応答は問題を引き起こす可能性があります）
  • フラッシュが正常に完了したことを確認します

4. 無効なリクエスト

• 症状：「Invalid Request」エラーが発生します
• デバッグ：サーバーには次の情報が記録されます：
  • 欠落しているフィールド（例：method、id）
  • JSON-RPC のバージョンの不一致
  • 無効なパラメーター
• 解決策：
  • すべてのリクエストが JSON-RPC 2.0 標準に準拠していることを確認します
  • method フィールドと id フィールドが存在することを確認します
  • パラメーターの構造を確認します

5. データベース接続の問題

• 症状：「Database error」エラーが発生します
• デバッグ：サーバーには次の情報が記録されます：
  • 使用された DB パス（デフォルトと上書き）
  • パスフレーズの状態（暗号化／復号化）
  • CipherProfile の設定
• 解決策：
  • ログに記録された DB パスを確認します
  • パスフレーズが正しく復号化されたことを確認します
  • CipherProfile の設定を確認します

デバッグ機能の詳細

サーバーは次の情報を自動的に記録します：

• 起動情報：

  • Java のバージョンと Java Home
  • オペレーティングシステムの情報
  • 引数の数と内容
  • 設定の解析状態

• リクエストの処理：

  • 番号と長さを含む、受信した各リクエスト
  • JSON-RPC の検証
  • パラメーターを含むメソッド呼び出し
  • 応答のサイズとステータス

• エラー処理：

  • スタックトレース付きの詳細な例外情報
  • 仕様に準拠した JSON-RPC エラーコード
  • 追加のデバッグデータを含むエラー応答

• データベース操作：

  • 使用された設定（デフォルトと上書き）
  • SQL クエリ（先頭 100 文字）
  • 結果のサイズと影響を受けた行数

データベースを開けない

• パスフレーズが正しいことを確認します
• データベースが SQLCipher 4 のデフォルト設定を使用していることを確認します（またはカスタムの暗号プロファイルを設定します）
• データベースファイルのパスが正しく、アクセス可能であることを確認します
• ログを確認します：サーバーには、パスフレーズの復号化と DB パスに関する詳細情報が記録されます

接続の問題

• Java がインストールされていることを確認します：java -version
• MCP の設定で JAVA_HOME が正しく設定されていることを確認します
• 詳細なエラーメッセージについては、MCP クライアントのログを確認します

FTS（全文検索）テーブル

サーバーは、メタデータにアクセスできないことがある FTS 仮想テーブルを自動的に処理します。これらのテーブルは、空のカラムリストとともに表示されます。

ライセンス

Apache License, Version 2.0 の下でライセンスされています。詳細については、LICENSE を参照してください。

サードパーティライセンス

• sqlite-jdbc-crypt（Apache License 2.0）- 暗号化をサポートする SQLite JDBC ドライバー
  • ソース：https://github.com/Willena/sqlite-jdbc-crypt
• Gson（Apache License 2.0）- Java 用 JSON ライブラリ
  • ソース：https://github.com/google/gson
• JUnit Jupiter（Eclipse Public License 2.0）- テスト用フレームワーク
  • ソース：https://junit.org/junit5/

詳細な帰属情報については、NOTICE を参照してください。

謝辞

• sqlite-jdbc-crypt - 暗号化をサポートする SQLite JDBC ドライバー
• Model Context Protocol - MCP 仕様

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。ガイドラインについては、CONTRIBUTING.mdをご覧ください。

サポート

問題や質問、コントリビューションについては、GitHubでイシューを作成してください。

コーヒーをごちそうしてください

この連携機能を気に入っていただけましたか？よろしければ、コーヒーをごちそうしてください！皆さんのご支援が、便利な機能の開発を続ける励みになります。