MCP Encrypted Sqlite

🚀 加密SQLite MCP服務器

這是一個用於加密SQLite數據庫的Model Context Protocol (MCP) 服務器，藉助SQLCipher實現對加密SQLite數據庫的操作。該服務器提供了讀取數據庫結構、查詢表以及對加密SQLite數據庫執行CRUD操作的工具。

與所有MCP客戶端兼容（如Cursor、Claude Desktop等）。

可處理以下應用的加密數據庫：MoneyMoney、1Password、Signal、WhatsApp、Firefox、Telegram、KeePass等使用SQLCipher加密的應用。

🚀 快速開始

Cursor（一鍵安裝）

在Cursor中安裝此MCP服務器的最簡單方法是通過Cursor MCP Store：

1. 訪問 cursor.store/mcp/rosch100/mcp-encrypted-sqlite
2. 點擊 “添加到Cursor”
3. 按照提示配置數據庫路徑和密碼

其他MCP客戶端

此服務器可與任何兼容MCP的客戶端配合使用。有關設置說明，請參閱下面的配置部分。

✨ 主要特性

• 加密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環境變量選擇開啟調試輸出
• 輸入驗證：對限制、偏移量和標識符進行全面驗證

📦 安裝指南

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。

💻 使用示例

可用工具

list_tables

列出數據庫中的所有表。默認情況下僅顯示錶名，若include_columns=true，還會顯示列詳細信息。

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

get_table_data

從表中讀取數據，可選擇過濾條件、列選擇和分頁。

{
  "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），這些工具使用參數化查詢。

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

insert_or_update

執行UPSERT操作（衝突時插入或更新）。

{
  "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

根據過濾條件從表中刪除行。

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

get_table_schema

檢索表的詳細模式信息（列、索引、外鍵、約束）。

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

list_indexes

列出表的所有索引。

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

📚 詳細文檔

配置

此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不在系統路徑中或使用自定義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提供經過身份驗證的加密
• 弱密鑰會被自動拒絕

調試模式

服務器支持通過MCP_DEBUG環境變量選擇開啟調試輸出。啟用後，詳細的調試信息將寫入stderr（而非stdout，以符合MCP協議要求）。

{
  "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版本、操作系統、參數）
• 配置解析詳細信息
• 請求處理信息
• 響應大小和結構
• 數據庫連接詳細信息 注意：默認情況下，調試輸出是禁用的，以保持日誌的簡潔。僅在排查問題時啟用。

默認加密配置文件

服務器默認使用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日誌”）
• 所有調試輸出都寫入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解析錯誤
   • 症狀：日誌中出現“解析錯誤”
   • 調試：服務器記錄：
     • 接收到的JSON的前500個字符
     • 帶有堆棧跟蹤的精確異常
   • 解決方案：
     • 檢查MCP配置中的JSON結構
     • 確保JSON正確轉義
     • 驗證所有必需字段是否存在
3. 缺少或不正確的響應
   • 症狀：請求未得到響應或超時
   • 調試：服務器記錄：
     • 每個接收到的請求的ID和方法
     • 響應大小和狀態
     • 寫入後的刷新狀態
   • 解決方案：
     • 檢查STDOUT是否可用（啟動時記錄）
     • 檢查響應大小（非常大的響應可能會導致問題）
     • 驗證刷新是否成功
4. 無效請求
   • 症狀：出現“無效請求”錯誤
   • 調試：服務器記錄：
     • 缺少的字段（例如，method、id）
     • JSON - RPC版本不匹配
     • 無效參數
   • 解決方案：
     • 確保所有請求符合JSON - RPC 2.0標準
     • 驗證method和id字段是否存在
     • 檢查參數結構
5. 數據庫連接問題
   • 症狀：出現“數據庫錯誤”錯誤
   • 調試：服務器記錄：
     • 使用的數據庫路徑（默認值與覆蓋值）
     • 密碼短語狀態（加密/解密）
     • 加密配置文件配置
   • 解決方案：
     • 檢查日誌中的數據庫路徑
     • 驗證密碼短語是否正確解密
     • 檢查加密配置文件設置

數據庫無法打開

• 驗證密碼短語是否正確
• 檢查數據庫是否使用SQLCipher 4默認設置（或配置自定義加密配置文件）
• 確保數據庫文件路徑正確且可訪問
• 檢查日誌：服務器會記錄有關密碼短語解密和數據庫路徑的詳細信息

連接問題

• 驗證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 上提交問題。

請我喝咖啡

喜歡這個集成嗎？請我喝杯咖啡吧！您的支持有助於我繼續開發酷炫的功能。