db-mcp

一个只读的 MCP 服务器，它让 AI 代理可以安全访问一个小型 SQLite 商店数据库（shop.db）：结构发现、自由格式的只读 SQL 以及预构建的分析报表。

安装

npm install

Related MCP server: SQLite Read-Only MCP Server

配置

服务器从进程环境中读取 SHOP_DB_PATH 来定位数据库文件。它是可选的——如果未设置，服务器将使用项目根目录中的 shop.db。.env 文件不会被自动读取（没有 dotenv 依赖，package.json 的 scripts 中也没有 --env-file 标志）；.env.example 仅用于提醒变量名。请在服务器实际运行的环境中设置 SHOP_DB_PATH——对 stdio MCP 客户端而言，就是其配置中的 env 键（参见下面的“连接客户端”）。

构建

npm run build

运行

npm start
# or directly:
node dist/index.js

服务器通过 stdio 提供 MCP 服务——它需要由 MCP 客户端/主机作为子进程启动，而不是直接交互式运行。

连接客户端

通用 stdio MCP 客户端配置：

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/db-mcp/dist/index.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/shop.db" }
    }
  }
}

Claude Desktop：在 claude_desktop_config.json 的 mcpServers 下添加相同的块（各操作系统下的配置文件位置请参阅 MCP.md），然后重新启动 Claude Desktop。

工具

安全说明

• 数据库连接以 { readonly: true, fileMustExist: true } 打开——无论发送什么 SQL，SQLite 引擎本身都会在物理层面拒绝任何写操作。

• query 工具在语句到达数据库之前，还会验证输入是否是一条单独的 SELECT（或 WITH ... SELECT）语句；对于 INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/PRAGMA/ATTACH/DETACH/REPLACE/VACUUM/REINDEX/TRIGGER 以及多语句输入，它会返回一条友好的错误信息并拒绝执行。

• 错误会在每个工具的边界被捕获，并以 isError: true 和一条简短消息作为 MCP 工具结果返回——绝不会向客户端发送堆栈跟踪或文件系统路径。

• 所有日志都会输出到 stderr（console.error）——stdout 专门保留给 JSON-RPC 协议流。

测试

npm test

通过 tsx 运行 node --test，覆盖每个 *.test.ts 文件：包括针对真实 shop.db 的 SQL 防护、数据库连接以及每个工具查询逻辑的单元测试；此外还有一个端到端测试，会启动编译后的服务器，并通过 stdio 使用真实的 MCP 客户端对其进行驱动。

Docker

docker build -t db-mcp .
docker run -i db-mcp

本地运行服务器并不需要 Docker（上面的客户端配置期望的是一个本地 node 进程），不过这里提供一个可选的验证/运行方式。