db-query-mcp

让 AI 助手安全查询 SQLite 数据库的 MCP Server —— 只读强制、SQL 校验、结果封顶。

为什么做这个

给 AI 接数据库,最大的风险不是"查不到",而是三件事:

1. 误写 —— 模型把 SELECT 写成 UPDATE,或者 DROP TABLE 出现在"顺手清理"里

2. 灌爆上下文 —— 一句 SELECT * FROM orders 拉回 200 万行,对话直接崩

3. 读到不该读的 —— 路径没限制,db_path: ../../etc/passwd 之类的穿越

这个服务把这三条做成设计约束,而不是"提示词里提醒一句"。

Related MCP server: sqlite-analyst

三条安全边界

只读为什么需要这么多层 —— 对抗性测试与逐层隔离实验的真实教训:

• URI 注入:不转义直接拼 f"file:{path}?mode=ro" 时,文件名里的 # 会被解析成 fragment,把 ?mode=ro 整段丢弃 → 连接偷偷变成读写模式。 必须 quote() 转义路径。

• 两层各能拦什么(逐层隔离实测,每用例全新库):

  连接配置	journal_mode=WAL	user_version 写	INSERT
  仅 mode=ro	拦	拦	拦
  仅 query_only	拦不住(文件真变 WAL)	拦	拦
  两层叠加(本实现)	拦	拦	拦

  query_only 单独拦不住 journal_mode=WAL 是 SQLite 的 pragma 特性, 这正是两层都留的原因;行为由 test_each_layer_isolation 钉住。

• 括号传参绕过:PRAGMA user_version(123) 是 SQLite 的合法语法, 但等号检查拦不住它。只有"名字参数"类 pragma(table_info 等)才允许 带括号。

• 注释混淆与字符串误伤:DEL/**/ETE 在 SQLite 里等于 DELETE, 校验前必须剥注释;但剥注释必须引号感知 —— 字符串里的 '--x--' 不是注释,正则直接剥会破坏合法查询。实现用双视图扫描: 执行用 cleaned(注释删、字符串留),校验用 code_only(字符串遮蔽, 数据里的 DELETE/; 不会误判)。

这些点都是先被实际绕过、修复后才写进这段文档的(见 git 历史里的 fix(security) 提交和 TestSecurityRegressions 回归测试)。

安装

pip install -e .

配置(以 Claude Desktop 为例)

{
  "mcpServers": {
    "db-query": {
      "command": "db-query-mcp",
      "env": {
        "DB_QUERY_MCP_ROOT": "/path/to/your/databases"
      }
    }
  }
}

DB_QUERY_MCP_ROOT 支持多个目录,用 : 分隔(Linux/macOS)或 ;(Windows)。

工具

query

{
  "db_path": "data/app.db",
  "sql": "SELECT id, email FROM users WHERE created_at > '2026-01-01' LIMIT 50",
  "max_rows": 50
}

返回:

{
  "columns": ["id", "email"],
  "rows": [[1, "a@example.com"]],
  "row_count": 1,
  "truncated": false,
  "max_rows": 50
}

schema

不传 table:列出全部表和视图。 传 table:返回列定义(类型/非空/默认值/主键)和建表 SQL。

推荐工作流:先 schema 看结构,再写 query —— 这也是给模型的 instructions 里写明的。

会拒绝什么

[拒绝] 只允许 SELECT / WITH / PRAGMA / EXPLAIN 开头的只读查询     # UPDATE ...
[拒绝] 检测到写操作关键字: DROP(本服务只读)                       # SELECT 1; DROP TABLE x
[拒绝] 只允许单条语句,检测到多个分号
[拒绝] 路径不在允许的根目录内。允许: /home/me/data

测试

pip install -e ".[dev]"
pytest tests/ -v

License

MIT