# mcp-sqlite

**Repository Path**: openminds/mcp-sqlite

## Basic Information

- **Project Name**: mcp-sqlite
- **Description**: 基于 Model Context Protocol (MCP) 的 SQLite 数据库交互服务器，为 AI 编程助手提供全面的数据库操作能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Sqlite, MCP, TypeScript

## README

# MCP SQLite Server

基于 Model Context Protocol (MCP) 的 SQLite 数据库交互服务器，为 AI 编程助手提供全面的数据库操作能力。

![mcp-sqlite](.readme/mcp-sqlite.jpg)

## 特性

### 数据库操作

- **完整 CRUD** — 创建、查询、更新、删除记录
- **自定义 SQL** — 执行任意 SQL 查询（含参数化绑定）
- **批量插入** — 单次操作插入多条记录
- **事务控制** — `begin` / `commit` / `rollback` 完整事务支持

### 数据库探索

- **数据库信息** — 路径、大小、表数量、日志模式
- **表结构查询** — 列名、类型、主键、约束
- **索引管理** — 列出、创建、删除索引
- **数据库统计** — 页大小、页数量、已用/空闲空间

### 数据导出

- **JSON / CSV 格式** — 导出整表或查询结果
- **文件输出** — 支持写入指定文件路径或直接返回内容

### 安全机制

- **SQL 安全防护** — 自动拦截 `DROP` / `ALTER` / `TRUNCATE` 等危险操作
- **只读模式** — `--read-only` 禁止所有写操作
- **审计日志** — `--audit-log` 记录所有操作到 JSON Lines 文件
- **SQL 注入防护** — 表名/列名校验 + 标识符转义 + 参数化查询

### 性能优化

- **WAL 模式** — 默认启用，提升并发读写性能
- **预编译语句缓存** — LRU 缓存，减少重复编译开销
- **分页查询增强** — `includeCount` 参数返回匹配总数

## 快速开始

### 前置准备

本项目未发布到 npm，需要先克隆并编译：

```bash
# 克隆仓库
git clone https://gitee.com/openminds/mcp-sqlite.git
cd mcp-sqlite

# 安装依赖
npm install

# 编译 TypeScript
npm run build
```

编译完成后，`dist/` 目录即为可运行的服务入口。下文中的 `<MCP_SQLITE_DIR>` 指代项目根目录的绝对路径（如 `e:/TRAE.ai/mcp-sqlite`）。

### 客户端配置

在 AI 客户端的 MCP 配置中，使用 `node` 指向 `dist/index.js`：

**Claude Desktop:**

在配置文件中添加（macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`，Windows: `%APPDATA%\Claude\claude_desktop_config.json`）：

```json
{
    "mcpServers": {
        "mcp-sqlite": {
            "command": "node",
            "args": [
                "<MCP_SQLITE_DIR>/dist/index.js",
                "<path-to-your-sqlite-database.db>"
            ]
        }
    }
}
```

**Claude Code (CLI):**

通过命令行添加 MCP 服务器：

```bash
# 添加服务器
claude mcp add mcp-sqlite -- node <MCP_SQLITE_DIR>/dist/index.js <path-to-your-database.db>

# 查看已添加的服务器
claude mcp list

# 使用只读模式
claude mcp add mcp-sqlite -- node <MCP_SQLITE_DIR>/dist/index.js <path-to-your-database.db> --read-only
```

数据库路径作为第一个参数传入，支持相对路径和绝对路径。

### 替代方案：全局命令注册

如果不想在每次配置中写完整路径，可通过以下方式注册全局命令：

#### npm link（推荐）

```bash
cd <MCP_SQLITE_DIR>
npm link
```

之后可在任意位置使用 `mcp-sqlite-server` 命令，配置简化为：

```json
{
    "mcpServers": {
        "mcp-sqlite": {
            "command": "mcp-sqlite-server",
            "args": ["<path-to-your-database.db>"]
        }
    }
}
```

取消全局链接：

```bash
npm unlink -g mcp-sqlite
```

#### npm pack + 全局安装

```bash
cd <MCP_SQLITE_DIR>
npm pack
npm install -g mcp-sqlite-2.0.1.tgz
```

安装后配置同 npm link。

### 启动参数

| 参数 | 环境变量 | 说明 | 默认值 |
|------|----------|------|--------|
| `<db-path>` | — | SQLite 数据库文件路径 | `mydatabase.db` |
| `--read-only` | `MCP_SQLITE_READ_ONLY=true` | 只读模式，禁止写操作 | `false` |
| `--allow-unsafe` | `MCP_SQLITE_ALLOW_UNSAFE=true` | 允许危险 SQL（关闭安全拦截） | `false` |
| `--audit-log <path>` | `MCP_SQLITE_AUDIT_LOG=<path>` | 审计日志文件路径（JSON Lines） | 禁用 |
| `--no-wal` | `MCP_SQLITE_NO_WAL=true` | 禁用 WAL 日志模式 | `false` |
| `--cache-size <n>` | `MCP_SQLITE_CACHE_SIZE=<n>` | 预编译语句缓存大小 | `50` |

> 参数优先级：命令行参数 > 环境变量 > 默认值

## 工具列表

### 数据库信息

| 工具 | 说明 | 参数 |
|------|------|------|
| `db_info` | 获取数据库基本信息（路径、大小、表数量、日志模式、只读状态） | 无 |
| `list_tables` | 列出所有用户表（排除 `sqlite_%` 系统表） | 无 |
| `get_table_schema` | 获取表的列结构详情（列名、类型、主键、非空约束等） | `tableName` |
| `db_stats` | 获取数据库统计信息（页大小、页数量、已用/空闲空间、日志模式） | 无 |

### CRUD 操作

| 工具 | 说明 | 参数 |
|------|------|------|
| `create_record` | 插入一条记录 | `table`, `data` |
| `read_records` | 查询记录（支持条件过滤、分页、总数统计） | `table`, `conditions?`, `limit?`, `offset?`, `includeCount?` |
| `update_records` | 更新符合条件的记录 | `table`, `data`, `conditions` |
| `delete_records` | 删除符合条件的记录 | `table`, `conditions` |
| `batch_create` | 批量插入多条记录（自动包裹事务） | `table`, `records` |

### 事务控制

| 工具 | 说明 | 参数 |
|------|------|------|
| `begin_transaction` | 开启事务 | `type?` (`deferred` / `immediate` / `exclusive`) |
| `commit_transaction` | 提交当前事务 | 无 |
| `rollback_transaction` | 回滚当前事务 | 无 |

### 索引管理

| 工具 | 说明 | 参数 |
|------|------|------|
| `list_indexes` | 列出表的所有索引（含列信息） | `tableName` |
| `create_index` | 创建索引 | `table`, `columns`, `unique?`, `name?` |
| `drop_index` | 删除索引 | `indexName` |

### 数据导出

| 工具 | 说明 | 参数 |
|------|------|------|
| `export_table` | 导出整表为 JSON 或 CSV | `table`, `format`, `outputPath?` |
| `export_query` | 导出查询结果为 JSON 或 CSV | `sql`, `values?`, `format`, `outputPath?` |

### 数据库维护

| 工具 | 说明 | 参数 |
|------|------|------|
| `vacuum` | 重整数据库文件，回收未使用空间（事务中不可执行） | 无 |

### 自定义查询

| 工具 | 说明 | 参数 |
|------|------|------|
| `query` | 执行任意 SQL 查询 | `sql`, `values?` |

> **安全提示：** 默认拦截 `DROP`、`ALTER`、`CREATE TABLE` 等危险操作。使用 `--allow-unsafe` 可关闭此保护。

## 使用示例

### 基础 CRUD

```json
// 创建记录
{
  "name": "create_record",
  "arguments": {
    "table": "users",
    "data": { "name": "Alice", "email": "alice@example.com", "age": 30 }
  }
}

// 条件查询 + 分页 + 总数
{
  "name": "read_records",
  "arguments": {
    "table": "users",
    "conditions": { "age": 30 },
    "limit": 10,
    "offset": 0,
    "includeCount": true
  }
}
```

### 事务操作

```json
// 开启事务
{ "name": "begin_transaction", "arguments": { "type": "immediate" } }

// 执行多条写操作...
{ "name": "create_record", "arguments": { "table": "orders", "data": { "...": "..." } } }
{ "name": "update_records", "arguments": { "table": "inventory", "data": { "...": "..." }, "conditions": { "...": "..." } } }

// 提交或回滚
{ "name": "commit_transaction", "arguments": {} }
```

### 批量插入

```json
{
  "name": "batch_create",
  "arguments": {
    "table": "users",
    "records": [
      { "name": "Alice", "email": "alice@example.com", "age": 30 },
      { "name": "Bob", "email": "bob@example.com", "age": 25 },
      { "name": "Charlie", "email": "charlie@example.com", "age": 35 }
    ]
  }
}
```

### 索引管理

```json
// 创建唯一索引
{
  "name": "create_index",
  "arguments": {
    "table": "users",
    "columns": ["email"],
    "unique": true
  }
}

// 列出索引
{ "name": "list_indexes", "arguments": { "tableName": "users" } }
```

### 数据导出

```json
// 导出为 CSV 文件
{
  "name": "export_table",
  "arguments": {
    "table": "users",
    "format": "csv",
    "outputPath": "/tmp/users.csv"
  }
}

// 导出查询结果为 JSON（直接返回内容）
{
  "name": "export_query",
  "arguments": {
    "sql": "SELECT name, email FROM users WHERE age > ?",
    "values": [25],
    "format": "json"
  }
}
```

### 自定义查询

```json
{
  "name": "query",
  "arguments": {
    "sql": "SELECT u.name, COUNT(p.id) as post_count FROM users u LEFT JOIN posts p ON u.id = p.user_id GROUP BY u.id",
    "values": []
  }
}
```

## 审计日志

使用 `--audit-log` 启用审计日志后，所有操作将记录为 JSON Lines 格式：

```json
{"timestamp":"2026-07-08T12:00:00.000Z","tool":"query","args":{"sql":"SELECT * FROM users"},"status":"success","durationMs":12,"rowCount":10}
{"timestamp":"2026-07-08T12:00:01.000Z","tool":"create_record","args":{"table":"users","data":{"keys":["name","email"]}},"status":"success","durationMs":5}
```

日志会对敏感数据进行脱敏处理：
- `data` / `records` — 仅记录键名，不记录值
- `conditions` — 仅记录键名，不记录值
- `sql` — 超过 500 字符自动截断

## 本地开发

### 环境要求

- Node.js >= 18.0.0

### 命令

```bash
# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 开发模式（监听文件变化）
npm run dev

# 运行测试
npm test

# 测试监听模式
npm run test:watch

# 清理并重装
npm run clean
```

### 本地启动服务

编译完成后，通过 `node` 直接运行：

```bash
# 基本启动（使用指定数据库文件）
node dist/index.js mydata.db

# 使用绝对路径
node dist/index.js /path/to/database.db

# 只读模式
node dist/index.js mydata.db --read-only

# 开启审计日志
node dist/index.js mydata.db --audit-log ./audit.jsonl

# 禁用 WAL 模式
node dist/index.js mydata.db --no-wal

# 组合使用
node dist/index.js mydata.db --read-only --audit-log ./audit.jsonl
```

> **注意：** 该服务基于 **stdio 传输**，启动后不会输出日志到控制台，而是通过标准输入/输出与 MCP 客户端（IDE）通信。服务运行时没有输出是正常现象。

### 调试

使用 MCP Inspector 进行可视化调试：

```bash
npx @modelcontextprotocol/inspector node dist/index.js test.db
```

### 项目结构

```
src/
├── index.ts              # 入口：解析参数、初始化依赖、启动服务器
├── config.ts             # 配置管理（命令行参数 + 环境变量）
├── types.ts              # 类型定义
├── db/
│   ├── Database.ts       # 数据库连接封装
│   └── StatementCache.ts # 预编译语句 LRU 缓存
├── security/
│   ├── SqlGuard.ts       # SQL 危险操作拦截
│   └── AuditLogger.ts    # 审计日志
├── tools/
│   └── index.ts          # MCP 工具注册（19 个工具）
└── utils/
    ├── identifiers.ts    # SQL 标识符转义与验证
    └── formatters.ts     # JSON / CSV 格式化
```

## 测试

项目包含完整的测试体系，覆盖单元测试、集成测试和端到端（E2E）测试。

### 测试数据库

首先生成测试数据库 `test.db`：

```bash
npm run test:db
```

生成的测试数据库包含：

| 表名 | 记录数 | 说明 |
|------|--------|------|
| `users` | 20 | 用户表，含唯一索引 `idx_users_email` |
| `posts` | 10 | 文章表，含索引 `idx_posts_user_id`、`idx_posts_published` |
| `comments` | 6 | 评论表 |
| `tags` | 6 | 标签表 |
| `post_tags` | 10 | 文章-标签关联表（多对多） |
| `empty_table` | 0 | 空表，用于边界测试 |

### 测试命令

```bash
# 运行所有测试（单元 + 集成）
npm test

# 测试监听模式（开发时使用）
npm run test:watch

# 运行 E2E 测试（启动真实服务，通过 JSON-RPC 验证）
npm run test:e2e
```

### 测试体系

| 测试类型 | 测试文件 | 数量 | 覆盖范围 |
|----------|----------|------|----------|
| 单元测试 | `tests/unit/formatters.test.ts` | 15 | JSON / CSV 格式化工具 |
| 单元测试 | `tests/unit/identifiers.test.ts` | 12 | SQL 标识符转义与构建 |
| 单元测试 | `tests/unit/sql-guard.test.ts` | 23 | SQL 安全防护规则 |
| 单元测试 | `tests/unit/statement-cache.test.ts` | 7 | 预编译语句 LRU 缓存 |
| 单元测试 | `tests/unit/audit-logger.test.ts` | 12 | 审计日志（脱敏、目录创建） |
| 单元测试 | `tests/unit/config.test.ts` | 15 | 配置解析（命令行 + 环境变量） |
| 集成测试 | `tests/integration/database.test.ts` | 22 | Database 类完整功能 |
| 集成测试 | `tests/integration/tools.test.ts` | 37 | 全部 19 个 MCP 工具调用链 |
| E2E 测试 | `tests/e2e-mcp.mjs` | 66 断言 | 真实启动服务，JSON-RPC 全链路验证 |

> **总计：143 个测试用例 + 66 个 E2E 断言，全部通过**

## 技术栈

- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [sqlite3](https://github.com/TryGhost/node-sqlite3)
- [TypeScript](https://www.typescriptlang.org/)
- [Zod](https://zod.dev/)
- [Vitest](https://vitest.dev/)

## 仓库地址

[https://gitee.com/openminds/mcp-sqlite](https://gitee.com/openminds/mcp-sqlite)

## 许可证

ISC