Shop Analytics MCP

基于 TypeScript 的 MCP 服务器，用于安全分析在线商店的 SQLite 数据库。仅通过 stdio 工作，并提供六个专用工具；不接受任意 SQL。

要求

• Node.js 24.10+;

• npm;

• sqlite3 CLI 仅用于重新应用迁移。

Related MCP server: mcp-analytics-server

安装与运行

npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start

SHOP_DB_PATH 具有优先级。如果未设置该变量，服务器将在当前工作目录中查找 shop.db。数据库路径未硬编码在源代码中。

数据

仓库中包含已迁移的现成 shop.db。它包含客户国家和 2025 年的数据。货币值视为 EUR，不进行转换。

要一次性将迁移应用到原始数据库：

npm run migrate

原始模式位于 database/schema.sql，确定性迁移位于 database/001-add-analytics-data.sql。

连接到客户端

现成的配置模板位于 config/：

• claude-code.mcp.json;

• codex.mcp.json;

• cursor.mcp.json.

将所选模板中的 /absolute/path/to/mcp-server 替换为此项目的路径。所有配置都通过 stdio 运行 dist/src/index.js，并通过 SHOP_DB_PATH 传递 shop.db 的路径。

工具

财务和商品指标以及订单数量均排除 cancelled。金额在带有 Eur 后缀的字段中返回。排行榜接受从 1 到 100 的 limit；期间使用 YYYY-MM-DD 日期。

使用示例

下面展示了 MCP 客户端如何调用 get_database_schema 来描述表，然后调用 get_customer_metrics 来统计来自德国的客户。

安全性

• SQLite 以 readOnly: true 和 PRAGMA query_only = ON 打开。

• SQLite authorizer 禁止写入、DDL、ATTACH、DETACH 和事务。

• 所有值都作为 SQL 参数绑定。

• 工具不接受 SQL，因此代理无法传递破坏性语句。

• 验证错误不会泄露 SQL、绝对路径或堆栈跟踪。

测试

npm test

测试覆盖八个验收问题的参考答案、国家/地区参数中的 SQL 注入、对 DELETE 的禁止、数据库临时副本的 SHA-256 不变性，以及通过 stdio 的 MCP 交互。

验收问题

1. 显示所有可用的表，并解释每个表包含哪些信息。

2. 有多少客户来自德国？

3. 哪个国家的客户最多？

4. 哪位客户消费最多？

5. 销量前 5 的产品有哪些？

6. 按收入排名的前 3 个产品类别是什么？

7. 我们在 2025 年产生了多少收入？

8. 哪个客户下的订单最多？