sqlite-guard-mcp

让AI代理在不被信任的情况下操作你的SQLite数据库。 一个MCP服务器，提供四个工具——schema、query、execute、audit_log——以及 三个保证：

1. 读取操作无法写入。 query 在C语言层面以 SQLITE_OPEN_READONLY 打开的独立连接上运行。伪装成写入的语句（/* just checking */ UPDATE …）不会被正则表达式捕获——而是被SQLite本身拒绝。通过构造而非检查来强制执行。

2. 写入操作先进行试运行。 execute 在一个始终回滚的事务中执行语句，并报告将会发生什么（changes、lastInsertRowid）。提交需要重新调用并带上 confirm: true——代理必须两次声明其意图，而其操作员可以在两次声明之间看到预期的效果。

3. 已提交的写入会留下可追溯的痕迹。 在任何提交之前，数据库文件都会被快照（VACUUM INTO——即使在有活跃读取器的WAL模式下也能保证事务一致性）。写入及其仅追加的审计行在同一事务中提交：你不可能得到一个没有审计条目的更改，或者一个针对未发生更改的审计条目。

为什么存在这个项目

我运行着一个个人财务仪表板，其UI被设计为只读——其中的每个数字都由AI代理通过SQL进行编辑。这种架构非常棒（没有表单，没有写入端点，代理负责记账），直到某个代理运行了一个看起来合理但WHERE子句错误的UPDATE。

从运行该系统中得到的见解：代理SQL需要的不是更智能的模型，而是人类运维几十年来一直需要的东西——读写分离、计划/执行步骤、备份和审计日志。这个服务器将这四个东西打包在MCP后面，这样任何代理（Claude Code，或任何其他支持MCP的工具）都可以在任何SQLite文件上免费获得它们。

Related MCP server: SQLite Read-Only MCP Server

快速开始

npm install
npm run demo        # full guardrail walkthrough on a temp DB — 10 seconds, no setup
npm test            # 10 tests: rollback semantics, backup consistency, audit atomicity

将其接入Claude Code：

claude mcp add sqlite-guard \
  -e SQLITE_GUARD_DB=/path/to/app.db \
  -- npx tsx src/server.ts

或者以交互方式检查它：npx @modelcontextprotocol/inspector npx tsx src/server.ts （需要设置 SQLITE_GUARD_DB）。

工具

设计说明

• 试运行是真正的执行，而非基于 EXPLAIN 的估算：语句会真实运行（包括触发器、约束等所有内容）然后回滚。你看到的就是提交会做的事情——包括你可能会遇到的约束错误。

• 恢复就是复制一个文件。 备份是名为 <db>-backup-<timestamp> 的普通SQLite文件；从错误的已提交写入中恢复就是 cp 加重启，审计行会精确记录哪个快照先于哪个写入。

• 拒绝来自代理的 BEGIN/COMMIT——事务生命周期属于守卫。否则，一个意外的 BEGIN 会让后续语句提交“已回滚”的试运行。

• 审计表可以有意地通过 query 读取。 这里透明胜过保密：代理可以审查自己的历史，操作员可以要求代理总结它更改了什么以及何时更改。

• 语句分类（classify.ts）是标记，而非安全措施。 它标记审计行和错误消息；安全边界是连接标志和事务协议。任何正则表达式能决定的东西，一个确定的输入也能推翻。

局限性（诚实的说明）

• 未实现按表的允许/拒绝列表（better-sqlite3 未暴露SQLite的授权器API）；边界是按数据库的。将服务器指向你打算让代理管理的数据库。

• VACUUM INTO 需要 SQLite ≥ 3.27（2019）；较旧的构建会回退到文件复制，这仅在数据库静止时才安全。

• 一个MCP服务器 = 一个数据库文件。为多个文件运行多个实例。

技术栈

TypeScript · @modelcontextprotocol/sdk（stdio 传输）· better-sqlite3 · zod · vitest。

许可证

MIT © Brandon Ta