内容
# 易用SQLite MCP
[模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，用 Node.js 和 TypeScript 实现，旨在使大型语言模型（LLM）可以直接与 SQLite 数据库交互。
本项目使用 Node.js、TypeScript、官方 MCP SDK 和 `better-sqlite3`。它通过标准输入输出运行，因此可以直接被 MCP 客户端（如 Claude Desktop、Codex 和 OpenCode）使用。
## 功能
- SQLite 连接管理，支持手动和固定启动模式
- 只读查询工具，用于数据检索
- 执行工具，用于数据修改和模式语句
- 模式发现工具，用于表、视图、索引和触发器
- 由 `better-sqlite3` 提供的轻量级同步 SQLite 访问
本项目中的 `better-sqlite3` 需要 Node.js 20 或更新版本。
## 要求
- Node.js 20 或更新版本
- npm
- 可访问的 SQLite 数据库文件
## 安装
直接使用 `npx` 运行服务器：
```bash
npx -y easy-sqlite-mcp
```
克隆仓库后的本地开发：
```bash
cd easy-sqlite-mcp
npm install
npm run build
```
## 配置
在 MCP 客户端配置或 shell 环境中，使用环境变量配置服务器。
| 变量 | 是否必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `SQLITE_PATH` | 否 | - | SQLite 数据库文件的绝对或相对路径。设置后，服务器以固定模式启动 |
示例 shell 配置：
```bash
SQLITE_PATH=/absolute/path/to/database.sqlite npx -y easy-sqlite-mcp
```
在 PowerShell 中：
```powershell
$env:SQLITE_PATH = "C:\data\database.sqlite"
npx -y easy-sqlite-mcp
```
服务器通过标准输入输出通信，通常由 MCP 客户端启动，而不是手动运行。
如果不确定工具的使用方法或操作失败，请先调用 `sqlite_manual`。它返回带有安全使用规则、占位符指导和生命周期说明的内置手册。
## 模式
易用 SQLite MCP 支持两种启动模式。服务器描述在启动时生成，以便 MCP 客户端和代理可以清楚地了解激活哪种模式。
### 手动模式
当未提供 `SQLITE_PATH` 时，使用手动模式。
在此模式下，代理必须显式打开和关闭数据库：
1. 在使用数据库工具之前，调用 `sqlite_open(path)` 打开数据库文件。
2. 使用查询、执行和模式发现工具。
3. 完成后调用 `sqlite_close` 关闭数据库。
一次只能打开一个 SQLite 数据库文件。打开另一个文件会首先关闭以前的连接。
服务器描述：
```text
手动：这是 SQLite 工具。使用前，请调用 sqlite_open(path) 打开数据库文件。使用后，请调用 sqlite_close 关闭数据库文件。一次只能打开一个数据库文件。
```
手动模式下的可用工具：
- `sqlite_open`
- `sqlite_close`
- `sqlite_status`
- `sqlite_query`
- `sqlite_execute`
- `sqlite_list_tables`
- `sqlite_describe_table`
### 固定模式
当 `SQLITE_PATH` 作为环境变量提供时，使用固定模式。
在此模式下，服务器在启动期间自动打开配置的 SQLite 数据库。代理不需要调用 `sqlite_open`，并且禁用连接切换。
服务器描述：
```text
固定：这是连接到路径 <SQLITE_PATH> 的 SQLite 工具。
```
固定模式下的可用工具：
- `sqlite_status`
- `sqlite_query`
- `sqlite_execute`
- `sqlite_list_tables`
- `sqlite_describe_table`
## Claude Desktop 示例
手动模式：
```json
{
"mcpServers": {
"easy-sqlite-mcp": {
"command": "npx",
"args": ["-y", "easy-sqlite-mcp"]
}
}
}
```
固定模式示例：
```json
{
"mcpServers": {
"easy-sqlite-mcp": {
"command": "npx",
"args": ["-y", "easy-sqlite-mcp"],
"env": {
"SQLITE_PATH": "/absolute/path/to/database.sqlite"
}
}
}
}
```
更新配置后重启 Claude Desktop。
## Codex config.toml 示例
手动模式：
```toml
[mcp_servers.easy-sqlite-mcp]
args = ["-y", "easy-sqlite-mcp"]
command = "npx"
enabled = true
```
固定模式示例：
```toml
[mcp_servers.easy-sqlite-mcp]
args = ["-y", "easy-sqlite-mcp"]
command = "npx"
enabled = true
[mcp_servers.easy-sqlite-mcp.env]
SQLITE_PATH = "/absolute/path/to/database.sqlite"
```
## OpenCode opencode.jsonc 示例
手动模式：
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"easy-sqlite-mcp": {
"type": "local",
"command": ["npx", "-y", "easy-sqlite-mcp"],
"enabled": true
}
}
}
```
固定模式示例：
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"easy-sqlite-mcp": {
"type": "local",
"command": ["npx", "-y", "easy-sqlite-mcp"],
"enabled": true,
"environment": {
"SQLITE_PATH": "/absolute/path/to/database.sqlite"
}
}
}
}
```
## 可用工具
| 工具 | 描述 |
| --- | --- |
| `sqlite_manual` | 返回内置手册。在不确定如何使用 SQLite 工具或需要帮助诊断操作错误时使用此工具 |
| `sqlite_open` | 打开 SQLite 数据库文件。仅限手动模式 |
| `sqlite_close` | 关闭当前数据库连接。仅限手动模式 |
| `sqlite_status` | 返回连接状态和当前数据库摘要 |
| `sqlite_query` | 执行只读 `SELECT` 查询 |
| `sqlite_execute` | 执行写入或修改 SQL 语句 |
| `sqlite_list_tables` | 列出数据库中的所有用户表 |
| `sqlite_describe_table` | 描述表的模式 |
## 手动模式说明
- 使用 `sqlite_open(path)` 打开数据库文件，然后调用查询或执行工具。
- 使用 `sqlite_close` 关闭数据库文件。
- 一次只能打开一个数据库文件。
- 需要生命周期或占位符指导时，使用 `sqlite_manual`。
## 开发
```bash
npm run build
npm run dev
npm test
```
## 许可证
MIT。参见 [LICENSE.md](LICENSE.md)。
