BILLZ MCP服务器
MCP服务器 比尔兹 POS/零售API 2.0。
模式
| 模式 | 工具 | 描述 |
|---|---|---|
analytics （默认） | 18 | 只读分析和查找——对AI代理安全 |
full | 80+ | 所有工具，包括写入操作（销售、核销、转账等） |
通过设置 BILLZ_MCP_MODE 环境变量。
设置
1.建造
cd billz_mcp
npm install
npm run build2.获取API密钥
在BILLZ管理中→ 设置→ 集成→ 创建API密钥。授予密钥 阅读 访问产品、销售、报告等。（BILLZ管理中的权限矩阵）。
2b。验证读取的API（可选）
调用与相同的HTTP路径 BILLZ_MCP_MODE=analytics （18个阅读工具）。使用 相同 您传递给MCP的秘密：
cd billz_mcp
npm install
BILLZ_SECRET_KEY='your_key' npm run smoke:read你也可以把 BILLZ_SECRET_KEY=... 在 billz_mcp/.env.退出代码 0 意味着每一张支票都通过了。
3.添加到游标（或任何MCP客户端）
{
"mcpServers": {
"billz": {
"command": "node",
"args": ["/absolute/path/to/billz_mcp/dist/index.js"],
"env": {
"BILLZ_SECRET_KEY": "your_secret_key_here",
"BILLZ_MCP_MODE": "analytics"
}
}
}
}环境变量
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
BILLZ_SECRET_KEY | 是 | - | BILLZ管理员提供的API集成密钥 |
BILLZ_MCP_MODE | 没有 | analytics | analytics （18个工具）或 full (80+) |
BILLZ_PLATFORM_ID | 否 | 内置 | 平台ID标头值 |
分析模式（默认）——18个工具
产品（2）
| 工具 | 说明 |
|---|---|
billz_get_products | 列出产品（通过增量同步 last_updated_date) |
billz_filter_products | 使用过滤器进行高级产品搜索 |
销售（3）
| 工具 | 说明 |
|---|---|
billz_get_sales | 列出已完成的销售 |
billz_get_sale_details | 单笔销售深度跳水 |
billz_search_sales | 高级销售搜索（v3） |
客户（3）
| 工具 | 说明 |
|---|---|
billz_get_customers | 列出/搜索客户 |
billz_get_customer | 单一客户详细信息 |
billz_get_debt_stats | 债务概况 |
报告（6）
| 工具 | 说明 |
|---|---|
billz_report_general_table | KPI仪表板（销售、产品、客户） |
billz_report_general_totals | KPI总计 |
billz_report_products_table | 按产品分类的销售额 |
billz_report_customers_table | 客户分析 |
billz_report_profit_loss | 损益 |
billz_report_stock | 按日期划分的库存水平 |
参考数据（4）
| 工具 | 说明 |
|---|---|
billz_get_shops | 店铺列表 |
billz_get_categories | 产品类别 |
billz_get_brands | 产品品牌 |
billz_get_product_characteristics | 自定义字段定义 |
完整模式——附加工具
集 BILLZ_MCP_MODE=full 解锁所有80多种工具，包括：
- 产品：创建、修补自定义字段
- 销售：创建草稿、添加产品、申请折扣、附加客户、完成、推迟、管理草稿
- 客户：创建、更新、设置余额、忠诚卡
- 供应商订单：创建、添加产品、更新、发送
- 转账：创建、添加产品、发送、取消、接受、更新
- 进口：大宗进口产品
- 促销：列出促销、详细信息、促销产品
- 注销：创建、添加产品、取消、完成、原因
- 盘点：列出会话
- 证书/礼品卡：搜索、创建、添加/删除销售、支付
- 报告：19个额外的报告工具（交易、绩效、进口、供应商等）
- 辅助：公司、用户、供应商、计量单位、现金箱、付款类型、货币
MCP资源
API文档作为MCP资源通过 billz://docs/{key} （两种模式都可用）。
项目结构
src/
index.ts Server init, mode gating, module registration
billz-client.ts HTTP client with JWT auth & 401 retry
helpers.ts Shared ok() helper, McpMode type
resources.ts MCP resources (API docs)
tools/
products.ts 2 analytics + 3 full
customers.ts 3 analytics + 7 full
sales.ts 3 analytics + 12 full
reports.ts 6 analytics + 19 full
auxiliary.ts 4 analytics + 10 full
orders.ts 6 full-only
transfers.ts 8 full-only
imports.ts 2 full-only
promotions.ts 3 full-only
writeoffs.ts 5 full-only
stocktaking.ts 1 full-only
certificates.ts 5 full-only