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 上提交问题。

请我喝咖啡

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