Encrypted SQLite MCP Server

用于加密 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

• 数据库探索：列出表、列、索引和 schema 元数据

• 查询支持：执行任意 SQL 查询（SELECT、INSERT、UPDATE、DELETE、DDL）

• CRUD 操作：支持带筛选地插入、更新和删除行

• 可配置的加密配置：支持不同的 SQLCipher 配置

• MCP 协议：通过 STDIO 完整实现 Model Context Protocol

• 安全性：对 SQL 标识符进行验证，以防止 SQL 注入

• 调试模式：通过 MCP_DEBUG 环境变量提供可选的调试输出

• 输入验证：对 limit、offset 和标识符进行全面验证

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（已包含 wrapper）

• 支持加密的 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（无文件锁）打开数据库。用于查看被其他应用（如 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

检索表的详细 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

这些设置与“DB Browser for SQLite”等工具在 SQLCipher 4 下使用的默认值一致。

开发

有关开发环境搭建、构建、测试和项目结构，请参阅 DEVELOPMENT.md。

安全注意事项

一般安全性

• 口令短语：口令短语仅存储在内存中，永远不会记录到日志中

• 加密口令短语：使用 AES-256-GCM 加密的口令短语，用于将口令短语存储在配置文件中（参见加密口令短语章节）

• 内存：请注意，解密后的口令短语会以 Java String（不可变）的形式保留在内存中。为了最大程度的安全，请考虑使用 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" 错误

• 调试：服务器会记录：

  • 使用的数据库路径（默认 vs. 覆盖）

  • 口令短语状态（已加密/已解密）

  • CipherProfile 配置

• 解决方案：

  • 检查日志中的数据库路径

  • 确认口令短语已正确解密

  • 检查 CipherProfile 设置

调试功能详解

服务器会自动记录：

• 启动信息：

  • Java 版本和 Java Home

  • 操作系统信息

  • 参数的数量和内容

  • 配置解析状态

• 请求处理：

  • 每个收到的请求及其编号和长度

  • JSON-RPC 验证

  • 带参数的方法调用

  • 响应大小和状态

• 错误处理：

  • 带有堆栈跟踪的详细异常信息

  • 符合规范的 JSON-RPC 错误码

  • 带有附加调试数据的错误响应

• 数据库操作：

  • 使用的配置（默认 vs. 覆盖）

  • SQL 查询（前 100 个字符）

  • 结果大小和受影响的行数

数据库无法打开

• 确认口令短语是否正确

• 检查数据库是否使用 SQLCipher 4 默认设置（或配置自定义 cipher profile）

• 确保数据库文件路径正确且可访问

• 检查日志：服务器会记录关于口令短语解密和数据库路径的详细信息

连接问题

• 确认 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 规范

贡献

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

支持

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

请我喝杯咖啡

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