spences10/mcp-sqlite-tools
GitHub: spences10/mcp-sqlite-tools
一个为 LLM 提供全面 SQLite 数据库操作的 MCP 服务器，通过细粒度的安全分级和事务支持，让 AI 助手安全高效地管理与查询本地数据库。
Stars: 14 | Forks: 4
# mcp-sqlite-tools
一个模型上下文协议 (MCP) 服务器，为 LLM 提供全面的 SQLite 数据库操作功能。该服务器使 AI 助手能够安全高效地与本地 SQLite 数据库进行交互，具备内置安全功能、高级事务支持以及清晰的只读和破坏性操作分离机制。
## 功能
### 🗄️ 数据库管理
- **打开/创建数据库**：打开现有数据库或创建新数据库
- **关闭数据库**：正确关闭数据库连接
- **列出数据库**：发现目录中的数据库文件
- **数据库信息**：获取全面的数据库元数据和统计信息
### 📊 表操作
- **列出表**：查看数据库中的所有表和视图
- **描述表**：获取表的详细 schema 信息
- **创建表**：使用自定义列定义创建新表
- **删除表**：移除表（带有安全警告）
### 🔍 查询操作
- **执行读取查询**：安全的 SELECT、PRAGMA 和 EXPLAIN 查询
- **执行写入查询**：INSERT、UPDATE、DELETE 操作
- **执行 Schema 查询**：DDL 操作 (CREATE, ALTER, DROP)
- **批量插入**：高效批量插入多条记录
### 💾 事务管理
- **开启事务**：启动支持 savepoint 的数据库事务
- **提交事务**：处理嵌套事务的提交更改
- **回滚事务**：安全地回滚更改和嵌套的 savepoint
- **自动清理**：自动清理过期的事务
### 📋 Schema 操作
- **导出 Schema**：将数据库 schema 导出为 SQL 或 JSON 格式
- **导入 Schema**：从 SQL 或 JSON 导入并执行 schema
- **选择性导出**：导出特定表或整个数据库结构
### 🛠️ 数据库维护
- **备份数据库**：创建带有时间戳的数据库备份
- **清理数据库**：优化数据库存储和性能
- **连接池**：带有健康监控的高级连接管理
## ⚠️ 安全功能
该服务器实现了多层安全机制：
- **查询分类**：自动分离只读、写入、schema 和事务操作
- **路径验证**：防止目录遍历攻击
- **可配置的路径限制**：控制对绝对路径的访问
- **输入验证**：使用 Valibot 进行全面的参数验证
- **高级连接池**：连接限制、健康监控和空闲超时
- **事务安全**：自动清理过期事务和嵌套 savepoint 支持
- **资源清理**：服务器关闭时的优雅清理与维护计划
### 基于安全 Hook 的工具分离
这些工具被有意划分为不同的类别，以便在 Claude Code 等 MCP 客户端中实现细粒度的审批控制：
**✓ 安全工具**（只读操作）：
- `execute_read_query` - SELECT、PRAGMA、EXPLAIN 查询
- `list_tables`、`describe_table`、`database_info`
- `export_schema`、`backup_database`
这些工具可以被自动批准或仅批准一次，允许 AI 自由探索您的数据库结构并读取数据。
**⚠️ 破坏性工具**（数据修改）：
- `execute_write_query` - INSERT、UPDATE、DELETE
- `bulk_insert` - 批量插入
- `import_csv` - CSV 数据导入
- `drop_table` - 永久删除表
这些工具应在每次操作时单独审批，让您能在数据被修改之前了解将要发生的更改。
**⚠️ SCHEMA 更改工具**（结构修改）：
- `execute_schema_query` - CREATE、ALTER、DROP 语句
- `create_table` - 创建表
- `import_schema` - 导入 schema
- `import_csv` - 可以从 CSV 头创建缺失的表
这些工具会修改数据库结构，应要求单独批准以防止意外的 schema 更改。
**⚠️ 文件写入工具**：
- `export_csv` - 写入 CSV 文件，包括绝对路径
**🔒 事务工具**：
- `begin_transaction`、`commit_transaction`、`rollback_transaction`
可以根据您的工作流需求进行配置。
**Claude Code Hook 配置示例：**
```
// In your Claude Code hooks
export function toolApproval(tool) {
// Auto-approve safe read operations
if (
tool.name.includes('read') ||
tool.name.includes('list') ||
tool.name.includes('describe') ||
tool.name.includes('export') ||
tool.name.includes('backup') ||
tool.name.includes('info')
) {
return 'auto-approve';
}
// Require approval for destructive operations
if (
tool.name.includes('write') ||
tool.name.includes('delete') ||
tool.name.includes('drop') ||
tool.name.includes('insert') ||
tool.name.includes('schema')
) {
return 'require-approval';
}
return 'require-approval'; // Default to safe
}
```
这种分离确保您能保持对破坏性操作的控制，同时允许 AI 高效地执行只读查询。
## 安装
### 从 npm 安装（发布后）
```
npm install -g mcp-sqlite-tools
```
### 从源码安装
```
git clone
cd mcp-sqlite-tools
pnpm install
pnpm run build
```
## 配置
### 环境变量
可以使用环境变量来配置服务器：
```
# SQLite 数据库的默认目录（相对于项目根目录）
SQLITE_DEFAULT_PATH=.
# 允许数据库文件的绝对路径（安全设置）
SQLITE_ALLOW_ABSOLUTE_PATHS=true
# SQLite 锁忙超时时间（以毫秒为单位，非挂钟查询运行时间）
SQLITE_BUSY_TIMEOUT=30000
# 数据库备份的默认备份目录
SQLITE_BACKUP_PATH=./backups
# 启用调试日志
DEBUG=false
```
### MCP 客户端配置
#### 选项 1：全局用户配置（推荐）
在您的 VS Code 用户设置中配置一次，即可在所有工作区中使用。请将其添加到您的全局 `mcp.json` 文件中（Windows 上为 `%APPDATA%\Code\User\mcp.json`）：
对于 VS Code 全局配置，请编辑 `~/.config/Code/User/mcp.json`（或 Windows 上的对应位置）：
```
{
"servers": {
"sqlite-tools": {
"command": "npx",
"args": ["-y", "mcp-sqlite-tools"]
}
}
}
```
**对于 WSL 用户**，请在您的全局配置中使用以下格式：
```
{
"servers": {
"sqlite-tools": {
"command": "wsl.exe",
"args": ["bash", "-c", "npx -y mcp-sqlite-tools"]
}
}
}
```
**优点：**
- ✅ **一次配置，到处适用** - 无需为每个项目单独设置
- 📁 **自动使用当前工作区** - 无论您打开哪个项目，都在其中创建数据库
- 🔄 **始终保持最新** - 通过 npx 使用最新发布的版本
#### 选项 2：工作区特定配置
对于希望通过版本控制共享数据库配置的团队，请在您的工作区中创建一个 `.vscode/mcp.json` 文件：
```
{
"servers": {
"sqlite-tools": {
"command": "npx",
"args": ["-y", "mcp-sqlite-tools"],
"env": {
"SQLITE_DEFAULT_PATH": "${workspaceFolder}/databases",
"SQLITE_ALLOW_ABSOLUTE_PATHS": "true",
"SQLITE_BACKUP_PATH": "${workspaceFolder}/backups"
}
}
}
}
```
**优点：**
- ✅ **团队共享** - 将配置提交到版本控制
- 📂 **有组织的结构** - 数据库位于专门的 `/databases` 文件夹中
- 🛡️ **项目隔离** - 每个项目都有自己的数据库配置
#### Claude Desktop / Cline 配置
将以下内容添加到您的 MCP 客户端配置中：
```
{
"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_BACKUP_PATH": "./backups"
}
}
}
}
```
### 环境变量
可以使用以下环境变量来配置 MCP 服务器：
| 变量 | 描述 | 默认值 | 示例 |
| ----------------------------- | ---------------------------------------- | ----------------------------- | ------------------------------ |
| `SQLITE_DEFAULT_PATH` | 数据库文件的默认目录 | `.` | `${workspaceFolder}/databases` |
| `SQLITE_ALLOW_ABSOLUTE_PATHS` | 在数据库操作中允许使用绝对路径 | `true` | `false` |
| `SQLITE_BACKUP_PATH` | 数据库备份的默认目录 | 与 `SQLITE_DEFAULT_PATH` 相同 | `./backups` |
| `SQLITE_BUSY_TIMEOUT` | SQLite 锁定忙碌超时时间（毫秒） | `30000` | `60000` |
`SQLITE_MAX_QUERY_TIME` 仍作为 `SQLITE_BUSY_TIMEOUT` 的已弃用别名被接受；它并不是一个实际运行时间的查询限制。
**路径解析：**
- 相对路径将从默认路径开始解析
- 在 VS Code 中使用 `${workspaceFolder}` 设置相对于工作区的路径
- 设置 `SQLITE_ALLOW_ABSOLUTE_PATHS=true` 以启用绝对路径操作
#### 开发配置
使用 MCP inspector 进行开发：
```
pnpm run build
pnpm run dev
```
## API 参考
### 数据库管理工具
#### `open_database`
打开或创建一个 SQLite 数据库文件。
**参数：**
- `path` (字符串，必填)：数据库文件的路径
- `create` (布尔值，可选)：如果不存在则创建（默认：true）
**示例：**
```
{
"path": "my-app.db",
"create": true
}
```
#### `close_database`
关闭数据库连接。
**参数：**
- `database` (字符串，可选)：要关闭的数据库路径
#### `list_databases`
列出目录中可用的数据库文件。
**参数：**
- `directory` (字符串，可选)：要搜索的目录
#### `database_info`
获取有关数据库的综合信息。
**参数：**
- `database` (字符串，可选)：数据库路径
### 表操作
#### `list_tables`
列出数据库中的所有表和视图。
**参数：**
- `database` (字符串，可选)：数据库路径
#### `describe_table`
获取表的 schema 信息。
**参数：**
- `table` (字符串，必填)：表名
- `database` (字符串，可选)：数据库路径
- `verbosity` (字符串，可选)：'summary' 或 'detailed'（默认：'detailed'）
**请求示例：**
```
{
"table": "users",
"verbosity": "detailed"
}
```
**响应示例：**
```
{
"database": "/tmp/demo.db",
"table": "users",
"columns": [
{
"name": "id",
"type": "INTEGER",
"nullable": true,
"default_value": null,
"primary_key": true
},
{
"name": "name",
"type": "TEXT",
"nullable": false,
"default_value": null,
"primary_key": false
},
{
"name": "email",
"type": "TEXT",
"nullable": true,
"default_value": null,
"primary_key": false
},
{
"name": "created_at",
"type": "TIMESTAMP",
"nullable": true,
"default_value": "CURRENT_TIMESTAMP",
"primary_key": false
}
],
"verbosity": "detailed",
"column_count": 4
}
```
#### `create_table`
创建具有指定列的新表。
**参数：**
- `name` (字符串，必填)：表名
- `columns` (数组，必填)：列定义
- `database` (字符串，可选)：数据库路径
**列定义：**
```
{
"name": "column_name",
"type": "TEXT|INTEGER|REAL|BLOB",
"nullable": true,
"primary_key": false,
"default_value": null
}
```
**示例：**
```
{
"name": "users",
"columns": [
{
"name": "id",
"type": "INTEGER",
"primary_key": true,
"nullable": false
},
{
"name": "name",
"type": "TEXT",
"nullable": false
},
{
"name": "email",
"type": "TEXT",
"nullable": true
}
]
}
```
#### `drop_table`
永久删除一个表及其所有数据。
**参数：**
- `table` (字符串，必填)：要删除的表名
- `database` (字符串，可选)：数据库路径
### 查询操作
#### `execute_read_query`
执行只读 SQL 查询（SELECT、PRAGMA、EXPLAIN）。
**参数：**
- `query` (字符串，必填)：SQL 查询
- `params` (对象，可选)：查询参数
- `database` (字符串，可选)：数据库路径
- `limit` (数字，可选)：返回的最大行数（默认：10000）
- `offset` (数字，可选)：要跳过的行数（默认：0）
- `verbosity` (字符串，可选)：'summary' 或 'detailed'（默认：'detailed'）
**请求示例：**
```
{
"query": "SELECT * FROM users ORDER BY id",
"verbosity": "detailed"
}
```
**响应示例：**
```
{
"database": "/tmp/demo.db",
"query": "SELECT * FROM users ORDER BY id LIMIT 10000",
"result": {
"rows": [
{
"id": 1,
"name": "Alice Johnson",
"email": "alice@example.com",
"created_at": "2025-10-03 09:42:04"
},
{
"id": 3,
"name": "Carol White",
"email": "carol@example.com",
"created_at": "2025-10-03 09:42:10"
}
],
"changes": 0,
"last_insert_rowid": 0
},
"row_count": 2,
"pagination": {
"limit": 10000,
"offset": 0,
"returned_count": 2,
"has_more": false
},
"verbosity": "detailed"
}
```
#### `execute_write_query`
执行修改数据的 SQL (INSERT、UPDATE、DELETE)。
**参数：**
- `query` (字符串，必填)：SQL 查询
- `params` (对象，可选)：查询参数
- `database` (字符串，可选)：数据库路径
**请求示例：**
```
{
"query": "INSERT INTO users (name, email) VALUES ('Alice Smith', 'alice@example.com')"
}
```
**响应示例：**
```
{
"database": "/tmp/demo.db",
"query": "INSERT INTO users (name, email) VALUES ('Alice Smith', 'alice@example.com')",
"result": {
"rows": [],
"changes": 1,
"last_insert_rowid": 1
},
"message": "⚠️ DESTRUCTIVE OPERATION COMPLETED: Data modified in database '/tmp/demo.db'. Rows affected: 1"
}
```
#### `execute_schema_query`
执行 DDL 查询（CREATE、ALTER、DROP）。
**参数：**
- `query` (字符串，必填)：DDL SQL 查询
- `params` (对象，可选)：查询参数
- `database` (字符串，可选)：数据库路径
**请求示例：**
```
{
"query": "CREATE TABLE users (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL,\n email TEXT UNIQUE,\n created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n)"
}
```
**响应示例：**
```
{
"database": "/tmp/demo.db",
"query": "CREATE TABLE users (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL,\n email TEXT UNIQUE,\n created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n)",
"result": {
"rows": [],
"changes": 0,
"last_insert_rowid": 0
},
"message": "⚠️ SCHEMA CHANGE COMPLETED: Database structure modified in '/tmp/demo.db'. Changes: 0"
}
```
#### `bulk_insert`
批量插入多条记录。
**参数：**
- `table` (字符串，必填)：目标表名
- `data` (数组，必填)：要插入的对象数组
- `batch_size` (数字，可选)：每批记录数（默认：1000）
- `database` (字符串，可选)：数据库路径
**请求示例：**
```
{
"table": "users",
"data": [
{ "name": "David Lee", "email": "david@example.com" },
{ "name": "Emma Davis", "email": "emma@example.com" },
{ "name": "Frank Miller", "email": "frank@example.com" }
]
}
```
**响应示例：**
```
{
"success": true,
"database": "/tmp/demo.db",
"table": "users",
"inserted": 3,
"batches": 1,
"total_time": 0,
"message": "⚠️ DESTRUCTIVE OPERATION COMPLETED: 3 records inserted into table 'users' in database '/tmp/demo.db'"
}
```
### CSV 操作
#### `import_csv`
将带有表头的 CSV 文件导入到表中。如果表不存在，将根据 CSV 头和推断出的 SQLite 列类型创建该表。默认情况下会对值进行强制转换（`""`/`null` 转换为 NULL，数字转换为数字，布尔值转换为 1/0）。除非 `fail_fast` 为 true，否则将报告行级插入错误并继续插入成功的行。
**参数：**
- `table` (字符串，必填)：目标表名
- `file_path` (字符串，必填)：CSV 文件路径；允许绝对路径
- `database_name` (字符串，可选)：数据库路径或当前上下文名称
- `create_table` (布尔值，可选)：创建缺失的表（默认：true）
- `batch_size` (数字，可选)：每批的行数（默认：1000）
- `fail_fast` (布尔值，可选)：在遇到第一行错误时停止（默认：false）
- `max_errors` (数字，可选)：返回的最大行错误数（默认：100）
- `coerce_types` (布尔值，可选)：强制转换 CSV 字符串（默认：true）
- `delimiter`、`quote`、`escape`、`encoding` (可选)：CSV 解析选项
#### `export_csv`
将整个表或只读查询结果导出为 CSV。需提供 `table` 或 `query` 中的恰好一个。
**参数：**
- `file_path` (字符串，必填)：输出 CSV 路径；允许绝对路径
- `table` (字符串，可选)：要导出的表
- `query` (字符串，可选)：要导出的只读查询
- `database_name` (字符串，可选)：数据库路径或当前上下文名称
- `delimiter`、`record_delimiter`、`encoding` (可选)：CSV 输出选项
- `always_quote` (布尔值，可选)：引用每个字段（默认：false）
- `append` (布尔值，可选)：追加到现有文件（默认：false）
### 事务管理
#### `begin_transaction`
启动支持可选 savepoint 的数据库事务。
**参数：**
- `database` (字符串，可选)：数据库路径
**返回：** 用于跟踪的事务 ID
#### `commit_transaction`
提交当前事务或释放 savepoint**参数：**
- `database` (字符串，可选)：数据库路径
#### `rollback_transaction`
回滚当前事务或还原到 savepoint。
**参数：**
- `database` (字符串，可选)：数据库路径
### Schema 操作
#### `export_schema`
将数据库 schema 导出为 SQL 或 JSON 格式。
**参数：**
- `database` (字符串，可选)：数据库路径
- `format` (字符串，可选)：输出格式 - "sql" 或 "json"（默认："sql"）
- `tables` (数组，可选)：要导出的特定表
**示例：**
```
{
"format": "json",
"tables": ["users", "orders"]
}
```
#### `import_schema`
从 SQL 或 JSON 导入并执行 schema。
**参数：**
- `database` (字符串，可选)：数据库路径
- `schema` (字符串，必填)：要导入的 schema 内容
- `format` (字符串，可选)：输入格式 - "sql" 或 "json"（默认："sql"）
### 数据库维护
#### `backup_database`
使用 SQLite 的在线备份 API 创建一致的 SQLite 备份，包括可能仍在 WAL 文件中的已提交数据。
**参数：**
- `source_database` (字符串，可选)：源数据库路径
- `backup_path` (字符串，可选)：备份文件路径（如果未提供则自动生成）
#### `vacuum_database`
通过回收未使用的空间来优化数据库存储。
**参数：**
- `database` (字符串，可选)：数据库路径
## 安全准则
### 工具分类
服务器会自动将工具划分为以下安全类别：
1. **✓ 安全**：只读操作（SELECT、PRAGMA、EXPLAIN、数据库信息、备份）
2. **⚠️ 破坏性**：数据修改（INSERT、UPDATE、DELETE、批量插入、CSV 导入）
3. **⚠️ SCHEMA 更改**：结构修改（CREATE、ALTER、DROP、schema 导入、CSV 表创建）
4. **⚠️ 文件写入**：写入文件的导出操作，包括绝对 CSV 路径
5. **⚠️ 事务**：事务控制（BEGIN、COMMIT、ROLLBACK）
6. **✓ 维护**：优化操作（VACUUM、连接管理）
### 最佳实践
1. **始终使用参数化查询**以防止 SQL 注入
2. **在多步操作中使用事务**以确保数据一致性
3. 在执行前**检查破坏性操作**
4. 在进行重大 schema 更改前**创建备份**
5. **使用 bulk_insert** 高效插入大型数据集
6. 在执行导入/导出文件操作前**检查 CSV 绝对路径**
7. 在进行重大结构更改前**导出 schema**
8. 为不同操作类型**使用合适的工具**
9. 在高流量场景中**监控连接池**使用情况
## 开发
### 构建
```
pnpm run build
```
### 开发模式
```
pnpm run dev
```
### 清理
```
pnpm run clean
```
## 架构
该服务器采用模块化架构构建：
### 核心模块
- **`src/index.ts`**：主服务器入口点
- **`src/config.ts`**：使用 Valibot 验证的配置管理
### 数据库客户端
- **`src/clients/connection-manager.ts`**：带有健康监控的高级连接池
- **`src/clients/query-executor.ts`**：SQL 执行、批量操作和查询工具
- **`src/clients/transaction-manager.ts`**：带有 savepoint 的 ACID 事务管理
- **`src/clients/schema-manager.ts`**：Schema 导出/导入功能
- **`src/clients/sqlite.ts`**：主 SQLite 客户端接口和工具
### 工具处理器
- **`src/tools/handler.ts`**：工具注册编排器
- **`src/tools/admin-tools.ts`**：数据库和表管理工具
- **`src/tools/query-tools.ts`**：查询执行和批量操作工具
- **`src/tools/transaction-tools.ts`**：事务管理工具
- **`src/tools/schema-tools.ts`**：Schema 导出/导入工具
- **`src/tools/csv-tools.ts`**：CSV 导入/导出工具
- **`src/tools/context.ts`**：数据库上下文管理
### 通用工具
- **`src/common/types.ts`**：TypeScript 类型定义
- **`src/common/errors.ts`**：错误处理工具
- **`src/common/sql.ts`**：SQL 标识符和字面量辅助工具
- **`src/common/schema-sql.ts`**：SQLite schema 语句解析
这种模块化设计提供：
- **关注点分离**：每个模块都有单一的职责
- **可维护性**：易于测试、调试和扩展单个组件
- **可扩展性**：可以在不影响现有代码的情况下添加新功能
- **类型安全**：全面的 TypeScript 覆盖
## 依赖项
- **[tmcp](https://github.com/paoloricciuti/tmcp)**：现代 TypeScript MCP 框架
- **[better-sqlite3](https://github.com/WiseLibs/better-sqlite3)**：高性能 SQLite 驱动
- **[valibot](https://valibot.dev/)**：用于类型安全输入的轻量级验证库
- **[csv-parser](https://github.com/mafintosh/csv-parser)**：CSV 导入解析
- **[csv-writer](https://github.com/ryu1kn/csv-writer)**：CSV 导出写入
### 依赖项提供的关键特性
- **tmcp**：简化的 MCP 服务器开发，提供出色的 TypeScript 支持
- **better-sqlite3**：同步的 SQLite 操作，具有卓越的性能
- **valibot**：对所有工具参数进行运行时类型验证
- **csv-\***：带有类型强制转换和行级导入错误报告的带表头 CSV 导入/导出功能
## 贡献
欢迎贡献！请随时提交 Pull Request。
## 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件。
## 致谢
- 基于模型上下文协议构建
- 灵感来源于 [mcp-turso-cloud](https://github.com/spences10/mcp-turso-cloud)
- 使用 [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) 进行高性能 SQLite 操作
标签：AI助手, DLL 劫持, LLM工具, MCP, MCP服务器, MITM代理, RAG, Schema管理, SOC Prime, SQLite, 事务管理, 只读操作, 大语言模型, 威胁情报, 开发工具, 开发者工具, 数据交互, 数据导入导出, 数据库备份, 数据库操作, 数据库管理, 数据库维护, 数据清洗, 本地数据库, 模型上下文协议, 自动化攻击, 连接池