Easy Sqlite Mcp

easy-sqlite-mcp

一个使用 Node.js 和 TypeScript 实现的 Model Context Protocol (MCP) 服务，旨在让大模型能够直接与 SQLite 数据库交互。

此项目使用 Node.js、TypeScript、官方 MCP SDK 和 better-sqlite3。它通过 stdio 运行，因此可直接供 Claude Desktop、Codex 和 OpenCode 等 MCP 客户端使用。

功能

• 支持手动和固定启动模式的 SQLite 连接管理
• 用于检索数据的只读查询工具
• 用于修改数据和执行架构语句的执行工具
• 用于发现表、视图、索引和触发器的架构探索工具
• 由 better-sqlite3 提供的轻量级同步 SQLite 访问

此项目中的 better-sqlite3 要求 Node.js 22 或更高版本。为确保在 Windows 上能够可靠地获取预构建二进制文件，建议使用 Node.js 22 LTS。

要求

• Node.js 22 或更高版本（建议使用 Node.js 22 LTS）
• npm
• 可访问的 SQLite 数据库文件

安装

使用 npx 直接运行服务：

npx -y easy-sqlite-mcp

克隆仓库后进行本地开发：

cd easy-sqlite-mcp
npm install
npm run build

配置

在 MCP 客户端配置或 shell 环境中使用环境变量配置服务。

变量	必需	默认值	描述
SQLITE_PATH	否	-	SQLite 数据库文件的绝对或相对路径。设置后，服务将以固定模式启动

shell 配置示例：

SQLITE_PATH=/absolute/path/to/database.sqlite npx -y easy-sqlite-mcp

在 PowerShell 中：

$env:SQLITE_PATH = "C:\data\database.sqlite"
npx -y easy-sqlite-mcp

服务通过 stdio 通信，通常由 MCP 客户端启动，而不是手动运行。

如果不确定如何使用某个工具，或操作失败，请先调用 sqlite_manual。它会返回内置手册，其中包含安全使用规则、占位符说明和生命周期说明。

模式

Easy SQLite MCP 支持两种启动模式。服务描述会在启动时生成，让 MCP 客户端和 Agent 清楚了解当前启用的模式。

手动模式

未提供 SQLITE_PATH 时，将使用手动模式。

在此模式下，Agent 必须显式打开和关闭数据库：

1. 在使用数据库工具前，调用 sqlite_open(path)。
2. 使用查询、执行和架构探索工具。
3. 完成后调用 sqlite_close。

一次只能打开一个 SQLite 数据库文件。打开另一个文件前，会先关闭之前的连接。

服务描述：

Manual: This is a SQLite tool. Before using it, call sqlite_open(path) to open a database file. After use, call sqlite_close to close it. Only one database file can be open at a time.

手动模式下可用的工具：

• sqlite_open
• sqlite_close
• sqlite_status
• sqlite_query
• sqlite_execute
• sqlite_list_tables
• sqlite_describe_table

固定模式

将 SQLITE_PATH 设置为环境变量时，将使用固定模式。

在此模式下，服务会在启动时自动打开配置的 SQLite 数据库。Agent 无需调用 sqlite_open，且无法切换连接。

服务描述：

Fixed: This is a SQLite tool connected to Path:<SQLITE_PATH>

固定模式下可用的工具：

• sqlite_status
• sqlite_query
• sqlite_execute
• sqlite_list_tables
• sqlite_describe_table

Claude Desktop 示例

手动模式：

{
  "mcpServers": {
    "easy-sqlite-mcp": {
      "command": "npx",
      "args": ["-y", "easy-sqlite-mcp"]
    }
  }
}

固定模式示例：

{
  "mcpServers": {
    "easy-sqlite-mcp": {
      "command": "npx",
      "args": ["-y", "easy-sqlite-mcp"],
      "env": {
        "SQLITE_PATH": "/absolute/path/to/database.sqlite"
      }
    }
  }
}

更新配置后，重启 Claude Desktop。

Codex config.toml 示例

手动模式：

[mcp_servers.easy-sqlite-mcp]
args = ["-y", "easy-sqlite-mcp"]
command = "npx"
enabled = true

固定模式示例：

[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 示例

手动模式：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "easy-sqlite-mcp": {
      "type": "local",
      "command": ["npx", "-y", "easy-sqlite-mcp"],
      "enabled": true
    }
  }
}

固定模式示例：

{
  "$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。

开发

npm run build
npm run dev
npm test

许可证

MIT。请参阅 LICENSE.md。