mcp-sqlite-tools

mcp-sqlite-tools

用于安全执行本地 SQLite 数据库操作的模型上下文协议（MCP）服务。它为 MCP 客户端提供明确的读取、写入、架构、事务、CSV、备份和维护工具。

功能

• 打开、创建、检查、备份、清理和关闭 SQLite 数据库
• 列出、描述、创建和删除表
• 使用命名或位置参数运行分页读取查询
• 运行明确的写入和架构查询
• 导入和导出带表头的 CSV 文件
• 使用带嵌套保存点的事务
• 将架构导出和导入为 SQL 或 JSON
• 通过配置限制数据库和 CSV 路径
• 将有破坏性的工具分类，以便客户端应用审批策略
• 使用 Node 内置的 SQLite 驱动，无需依赖原生插件

要求

• Node.js 24.12 或更高版本
• 支持 stdio 服务的 MCP 客户端

配置 MCP 客户端

MCP 客户端通过 npx 启动此服务；无需全局安装。

使用 MCPick 安装

MCPick 可将此服务添加到受支持的客户端，无需手动编辑 JSON。默认情况下，此命令针对 Claude Code 的本地范围：

npx -y mcpick add \
  --name sqlite-tools \
  --command npx \
  --args "-y,mcp-sqlite-tools"

如有需要，可明确选择客户端和范围：

npx -y mcpick add \
  --name sqlite-tools \
  --command npx \
  --args "-y,mcp-sqlite-tools" \
  --client vscode \
  --scope project

add 命令支持 Claude Code、Gemini CLI、VS Code、Cursor、Windsurf、OpenCode 和 Pi。运行 npx mcpick clients，查看当前的客户端功能、范围和配置位置。

这些示例使用最新的软件包版本。若要使用可复现的配置，请将 --args 中的 mcp-sqlite-tools 替换为确切版本，例如 [email protected]。

手动配置

对于不受支持的客户端或高级配置，请手动添加此服务：

{
	"mcpServers": {
		"mcp-sqlite-tools": {
			"command": "npx",
			"args": ["-y", "mcp-sqlite-tools"],
			"env": {
				"SQLITE_DEFAULT_PATH": ".",
				"SQLITE_ALLOW_ABSOLUTE_PATHS": "true",
				"SQLITE_BUSY_TIMEOUT": "30000",
				"SQLITE_JOURNAL_MODE": "wal",
				"SQLITE_BACKUP_PATH": "./backups"
			}
		}
	}
}

VS Code 使用 servers 对象，而不是 mcpServers。更多面向特定客户端的示例，请参阅配置指南。

环境变量

变量	用途	默认值
SQLITE_DEFAULT_PATH	数据库文件的基础目录	.
SQLITE_ALLOW_ABSOLUTE_PATHS	允许使用默认目录以外的路径	true
SQLITE_BACKUP_PATH	默认备份目录	默认数据库路径
SQLITE_BUSY_TIMEOUT	SQLite 锁忙超时时间（毫秒）	30000
SQLITE_JOURNAL_MODE	delete、truncate、persist 或 wal	wal
DEBUG	启用诊断日志	false

当 SQLITE_ALLOW_ABSOLUTE_PATHS=false 时，相对路径和绝对路径都必须解析到 SQLITE_DEFAULT_PATH 内。不能使用符号链接逃出该目录。

对于文件同步目录中的数据库，请使用 SQLITE_JOURNAL_MODE=delete。不安全的 SQLite 模式 memory 和 off 不受支持。

SQLITE_MAX_QUERY_TIME 仍可作为已弃用的 SQLITE_BUSY_TIMEOUT 别名使用。它不会限制查询的实际运行时长。

工具

工具按用途分类，以便 MCP 客户端应用明确的审批规则。

安全且只读

工具	用途
open_database	打开现有数据库
close_database	关闭一个数据库连接
list_databases	查找目录中的数据库文件
database_info	读取文件和 SQLite 元数据
list_tables	列出表和视图
describe_table	读取列和约束
backup_database	创建一致的在线备份
export_csv	导出表或只读查询结果
export_schema	将架构导出为 SQL 或 JSON
execute_read_query	执行一条 SQLite 只读语句

写入、架构和维护

工具	用途
create_database	创建新的数据库文件
create_table	根据经过验证的列创建表
drop_table	删除表及其数据
execute_write_query	执行 INSERT、UPDATE 或 DELETE
execute_schema_query	执行一条架构语句
bulk_insert	分批插入记录
import_csv	导入带表头的 CSV 文件
import_schema	应用 SQL 或 JSON 架构对象
vacuum_database	重建数据库以回收空间
begin_transaction	开始事务或嵌套保存点
commit_transaction	提交事务或释放保存点
rollback_transaction	回滚事务或保存点

参数、响应、示例、分页和 CSV 选项请参阅完整 API 参考。

安全模型

此服务不会将所有 SQL 字符串一概而论：

• execute_read_query 使用 SQLite 的授权器 API，拒绝写入、架构更改、不安全的 PRAGMA、附加数据库和多条语句。
• 写入、架构、事务和破坏性管理操作使用独立工具，以便客户端请求审批。
• 在访问数据库和 CSV 文件前，会解析并验证其路径。
• 工具生成的标识符都会加引号。
• 值会作为参数绑定，而不是插入 SQL。
• 备份使用 SQLite 的在线备份 API，并包含已提交的 WAL 数据。

客户端可以允许使用只读工具，并要求对破坏性工具进行审批。批准更改前，请务必检查 SQL 和文件路径。更改架构、导入数据或进行大量写入前，请备份重要数据库。

为什么选择原生 SQLite？

使用 node:sqlite 可移除原生插件、其安装脚本及特定于平台的二进制文件。使用原生 SQLite 后，干净的生产环境安装大小从 better-sqlite3 的 31.3 MB 降至 3.6 MB，减少了 88.5%。npm 压缩包本身的大小则相近：原生版本为 63.1 KB，已发布版本为 60.0 KB。节省主要来自已安装的依赖树。

此次迁移还移除了 better-sqlite3 及其类型包。安装不再依赖预编译插件是否可用，也不再需要可用的原生编译器。

驱动基准测试

耗时越短越好。以下中位数使用 20,000 行数据，每个驱动预热两次并测量七次。每个样本都使用一个新数据库，且驱动顺序交替。除插入工作负载外，设置过程不计入测量范围。

工作负载	node:sqlite	better-sqlite3	原生结果
插入事务	11.13 ms	23.78 ms	快 2.14 倍
索引点查	25.23 ms	21.40 ms	慢 17.9%
全行扫描	6.39 ms	3.29 ms	慢 94.3%
更新事务	8.04 ms	15.40 ms	快 1.92 倍
在线备份	0.55 ms	0.38 ms	慢 45.0%

测试环境为 Linux x64、Node.js 24.15.0 和 AMD Ryzen AI 9 HX 370。Node 使用 SQLite 3.51.3；[email protected] 使用 SQLite 3.53.3。这些微基准测试展示的是驱动之间的权衡，并不能代表完整的 MCP 性能。测试未包含 MCP 传输和验证的开销。

开发

git clone https://github.com/spences10/mcp-sqlite-tools.git
cd mcp-sqlite-tools
pnpm install
pnpm run check
pnpm test
pnpm run build

有关模块职责及其他开发命令，请参阅 开发与架构。

文档

• 配置
• API 参考
• 开发与架构

贡献

欢迎提交问题和拉取请求。

许可证

MIT 许可证。请参阅 LICENSE。