暗号化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環境変数によるオプションのデバッグ出力

• 入力検証: 制限、オフセット、識別子の包括的な検証

Related MCP server: mcp-sqlite

なぜ暗号化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ストアを利用することです：

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仕様に従います。

サーバーは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:プレフィックス付き）を使用します：

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:で始まる）を自動的に検出して復号化します

• 強力なキー（256ビット/32バイト）を生成するにはPassphraseEncryption.generateKey()を使用します

• 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

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

開発

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

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

一般的なセキュリティ

• パスフレーズ: パスフレーズはメモリ内にのみ保存され、ログに記録されることはありません

• 暗号化パスフレーズ: 設定ファイルにパスフレーズを保存する場合は、AES-256-GCM による暗号化パスフレーズを使用します（暗号化パスフレーズセクションを参照）

• メモリ: 復号化されたパスフレーズは Java の String（不変）としてメモリ内に残ることに注意してください。最大限のセキュリティを追求するには、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

• JAVA_HOME が MCP 設定で正しく設定されていることを確認する

• 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 で issue を開いてください。

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

このインテグレーションが気に入りましたか？お気軽にコーヒーをごちそうしてください！あなたのサポートは、私が素晴らしい機能の開発を続けるのに役立ちます。