STARWARCLOUD STARWAR.AI
返回市场
MCP-SQLite工具

MCP-SQLite工具

作者：spences106 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

mcp-sqlite-tools

一个提供全面SQLite数据库操作的Model Context Protocol (MCP)服务器，适用于大型语言模型(LLMs)。该服务器使AI助手能够安全高效地与本地SQLite数据库进行交互，内置了安全特性、高级事务支持以及只读操作和破坏性操作之间的明确分离。

功能

🗄️ 数据库管理

  • 打开/创建数据库：打开现有数据库或创建新数据库
  • 关闭数据库：正确关闭数据库连接
  • 列出数据库：发现目录中的数据库文件
  • 数据库信息：获取全面的数据库元数据和统计信息

📊 表操作

  • 列出表：查看数据库中的所有表和视图
  • 描述表：获取表的详细模式信息
  • 创建表：使用自定义列定义创建新表
  • 删除表：移除表（带有安全警告）

🔍 查询操作

  • 执行读取查询：安全的SELECT、PRAGMA和EXPLAIN查询
  • 执行写入查询：INSERT、UPDATE、DELETE操作
  • 执行模式查询：DDL操作（CREATE、ALTER、DROP）
  • 批量插入：高效地批量插入多条记录

💾 事务管理

  • 开始事务：启动具有保存点支持的数据库事务
  • 提交事务：提交更改并处理嵌套事务
  • 回滚事务：安全地回滚更改和嵌套保存点
  • 自动清理：自动清理过时的事务

📋 模式操作

  • 导出模式：将数据库模式导出为SQL或JSON格式
  • 导入模式：从SQL或JSON导入并执行模式
  • 选择性导出：导出特定表或整个数据库结构

🛠️ 数据库维护

  • 备份数据库：创建带有时间戳的数据库备份
  • 优化数据库：优化数据库存储和性能
  • 连接池：高级连接管理，带健康监控

⚠️ 安全特性

此服务器实现了多层安全措施：

  • 查询分类：自动分离只读、写入、模式和事务操作
  • 路径验证：防止目录遍历攻击
  • 可配置路径限制：控制对绝对路径的访问
  • 输入验证：使用Valibot进行全面参数验证
  • 高级连接池：连接限制、健康监控和空闲超时
  • 事务安全性：自动清理过时的事务和嵌套保存点支持
  • 资源清理：在服务器关闭时优雅地清理，并安排维护

基于钩子的安全工具分离

这些工具被有意地分为不同的类别，以启用MCP客户端如Claude Code中的细粒度批准控制：

✓ 安全工具（只读操作）：

  • 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 - 批量插入
  • drop_table - 永久删除表

这些工具应针对每个操作单独批准，让您在数据被修改之前了解哪些数据将被修改。

⚠️ 模式变更工具（结构修改）：

  • execute_schema_query - CREATE、ALTER、DROP语句
  • create_table - 创建表
  • import_schema - 导入模式

这些工具会修改数据库结构，应单独批准以防止意外的模式更改。

🔒 事务工具：

  • begin_transaction、commit_transaction、rollback_transaction

可以根据您的工作流程需求进行配置。

示例Claude Code钩子配置：

// 在您的Claude Code钩子中
export function toolApproval(tool) {
	// 自动批准安全的读操作
	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';
	}

	// 需要批准破坏性操作
	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'; // 默认为安全
}

这种分离确保您能控制破坏性操作，同时允许AI高效地处理只读查询。

安装

从npm安装（当发布时）

npm install -g mcp-sqlite-tools

从源码安装

git clone <repository-url>
cd mcp-sqlite-tools
pnpm install
pnpm run build

配置

环境变量

服务器可以通过环境变量进行配置：

# SQLite数据库默认目录（相对于项目根目录）
SQLITE_DEFAULT_PATH=.

# 允许数据库文件使用绝对路径（安全设置）
SQLITE_ALLOW_ABSOLUTE_PATHS=true

# 最大查询执行时间（毫秒）
SQLITE_MAX_QUERY_TIME=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_MAX_QUERY_TIME": "30000",
				"SQLITE_BACKUP_PATH": "./backups"
			}
		}
	}
}

环境变量

以下环境变量可用于配置MCP服务器：

变量描述默认值示例
SQLITE_DEFAULT_PATH数据库文件的默认目录.${workspaceFolder}/databases
SQLITE_ALLOW_ABSOLUTE_PATHS允许数据库操作中的绝对路径truefalse
SQLITE_BACKUP_PATH数据库备份的默认目录与SQLITE_DEFAULT_PATH相同./backups
SQLITE_MAX_QUERY_TIME最大查询执行时间（毫秒）30-秒60000

路径解析：

  • 相对路径从默认路径解析
  • 在VS Code中使用${workspaceFolder}表示工作区相对路径
  • 设置SQLITE_ALLOW_ABSOLUTE_PATHS=true以启用绝对路径操作

开发配置

用于MCP检查器的开发：

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

获取表的模式信息。

参数：

  • 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,
		"lastInsertRowid": 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,
		"lastInsertRowid": 1
	},
	"message": "⚠️ 破坏性操作完成：数据库'/tmp/demo.db'中的数据已修改。受影响的行数：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,
		"lastInsertRowid": 0
	},
	"message": "⚠️ 模式变更完成：数据库结构在'/tmp/demo.db'中已修改。更改：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": "⚠️ 破坏性操作完成：3条记录已插入到数据库'/tmp/demo.db'中的表'users'"
}

事务管理

begin_transaction

启动具有可选保存点支持的数据库事务。

参数：

  • database (字符串，可选)：数据库路径

返回值： 用于