mcp-encrypted-sqlite

加密 SQLite MCP 服务

用于加密 SQLite 数据库的 MCP 服务

一个使用 SQLCipher 处理加密 SQLite 数据库的模型上下文协议（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 完整实现模型上下文协议
• 安全性：验证 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_QUICKSTART.md，了解 Docker Desktop 设置。

**详细配置：**请参阅 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 打开数据库（不使用文件锁）。可用于查看被其他应用（例如 MoneyMoney）独占锁定的数据库。此模式下，所有写入工具和 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 标志之前
• Docker 容器无法访问 macOS Keychain——请显式传递加密密钥
• 获取加密密钥：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（而非 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 默认设置：

• 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 字符串的形式保留在内存中（不可变）。为实现最高安全性，可考虑使用 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 路径（默认路径与覆盖路径）
  • 密码短语状态（已加密/已解密）
  • 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 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 规范

贡献

欢迎贡献！请随时提交 Pull Request。请参阅 CONTRIBUTING.md 了解指南。

支持

如有问题、疑问或想要贡献，请在 GitHub 上提交 issue。

请我喝杯咖啡

喜欢这个集成吗？欢迎请我喝杯咖啡！您的支持能帮助我继续开发有趣的功能。