MCP Encrypted Sqlite

🚀 暗号化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サーバーの大きな特徴です。
• 暗号化されたパスフレーズ: AES-256-GCMで暗号化されたパスフレーズをサポートし、macOS Keychainと統合されています。
• データベースの探索: テーブル、列、インデックス、スキーマメタデータを一覧表示できます。
• クエリのサポート: 任意の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-3.50.1.0.jar sqlite-jdbc-crypt から)

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 に配置されます。

🚀 クイックスタート

Cursor (ワンクリックインストール)

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

1. cursor.store/mcp/rosch100/mcp-encrypted-sqlite にアクセスします。
2. "Add to Cursor" をクリックします。
3. データベースパスとパスフレーズを設定するように促されるので、指示に従ってください。

その他のMCPクライアント

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

設定

このMCPサーバーは、すべてのMCP互換クライアント (Cursor、Claude Desktopなど) で動作します。設定形式は Model Context Protocol仕様 に従っています。 サーバーは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: 絶対パスを使用する場合は不要 (省略可能)
• 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: 接頭辞付き) を使用します:

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 セクションは必要ありません - キーは自動的に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 Keychain (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パス (デフォルト vs. オーバーライド)
  • パスフレーズの状態 (暗号化/復号化)
  • CipherProfileの設定
• 解決策:
  • ログ内のDBパスを確認してください。
  • パスフレーズが正しく復号化されたことを確認してください。
  • CipherProfileの設定を確認してください。

デバッグ機能の詳細

サーバーは自動的に以下を記録します:

• 起動情報:
  • JavaバージョンとJava Home
  • オペレーティングシステム情報
  • 引数の数と内容
  • 設定の解析ステータス
• リクエストの処理:
  • 受信した各リクエストの番号と長さ
  • JSON-RPCの検証
  • パラメータ付きのメソッド呼び出し
  • レスポンスのサイズとステータス
• エラー処理:
  • 詳細な例外情報とスタックトレース
  • 仕様に従ったJSON-RPCエラーコード
  • 追加のデバッグデータ付きのエラーレスポンス
• データベース操作:
  • 使用された設定 (デフォルト vs. オーバーライド)
  • 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 でイシューを開いてください。

支援をお願いします

この統合が気に入ったら、コーヒーをおごってくれませんか？あなたの支援により、私はクールな機能の開発を続けることができます。