caisse-enregistreuse-mcp-server

🚀 🧾 Kash MCP Server

Kash MCP Server 是一个符合 MCP（模型上下文协议） 的服务器，它允许 ChatGPT、Claude 等支持 MCP 的客户端连接到 销售记录系统（即 POS 收银机）。该服务器提供了一个简洁的接口，具备查看销售与收入、创建和记录收据、管理产品与库存，以及通过对话请求生成自动报告等功能。

🟢 在线服务器：https://mcp.kash.click

🚀 快速开始

将你的收银机与 ChatGPT、Claude 或 n8n 连接起来，只需通过对话就能轻松管理业务。

想象一下，你的收银机能够理解你的语句、执行你的命令并分析报告，无需任何点击操作。借助这个智能网关，free-cash-register.net 软件可以与 ChatGPT、Claude 和 n8n 兼容，将你的交互转化为实际行动。你只需说“记录 4 号桌两份咖啡的订单”或“显示 125 号订单的发票”，一切就能轻松完成。

你还可以询问“本周的收入是多少？”或“周二的最佳客户有哪些？”你的智能助手会直接与收银机通信并立即给出响应。这是一种全新的业务运营方式：更顺畅、更快速且极其自然。你的 声音成为了操作界面，而你的 智能助手成为了新同事。

这个项目将 kash.click API 作为 模型上下文协议（MCP） 工具公开，可通过 HTTP（可流式传输） 和/或 STDIO 访问。

✨ 主要特性

• 销售：支持 sale_create，可处理目录和自由行销售。
• 订单：获取指定日期范围内的订单列表。
• 数据（列表）：涵盖产品、部门、部门组、客户、变体、配送、支付方式、钱箱、配送区域、中继点、折扣、用户等信息。

💻 使用示例

基础用法

你可以向智能助手发出如下指令：

• 💬 “显示今天的销售情况”
• 💬 “记录 84 号桌两份咖啡和一份羊角面包的销售”
• 💬 “下午 6 点 15 分向杜邦夫人配送十支红玫瑰！”
• 💬 “生成本周的收银机报告”
• 💬 “今年外卖销售额是否有所增长？”
• 💬 “客户杜邦是否支付了订单？”

📦 安装指南

前提条件

你需要拥有一个 free-cash-register.net 账户。若没有，可在以下链接注册： https://kash.click/free-pos-software/ChatGPT

然后在软件的设置、网络服务页面获取你的 APIKEY 和 SHOPID。

Claude 安装步骤

最小化安装

编辑 Claude Desktop 配置目录中的 claude_desktop_config.json 文件：

• Windows：

%APPDATA%\Claude\claude_desktop_config.json

• Mac OS：

~/Library/Application Support/Claude/claude_desktop_config.json

将 SHOPID 和 APIKEY 替换后，提供以下内容：

{
  "mcpServers": {
    "caisse": {
      "command": "npx",
      "args": [
        "caisse-enregistreuse-mcp-server",
        "--shopid=[replaceWithYourSHOPID]",
        "--apikey=[replaceWithYourAPIKEY]"
      ]
    }
  }
}

通过 npx 安装

创建一个安装文件夹，并在 shell 中运行以下命令：

npx caisse-enregistreuse-mcp-server --shopid=12345 --apikey=abcdef123456

通过 npm 安装

# 1) 安装依赖
npm install

# 2) 配置环境变量（见下文）

# 3) 构建项目
npm run build

配置

二进制文件/运行器会启动 src/stdio.ts 并通过 MCP stdin/stdout 进行通信。编辑 Claude Desktop 配置目录中的 claude_desktop_config.json 文件，自定义安装路径并设置你的 SHOPID 和 APIKEY（从 https://kash.click 获取）：

{
  "mcpServers": {
    "caisse": {
      "command": "node",
      "args": [
        "{{PATH_TO_SRC}}/build/stdio.js"
      ],
      "cwd": "{{PATH_TO_SRC}}",
      "env": {
        "SHOPID": "16",
        "APIKEY": "XXXXXXXX"
      }
    }
  }
}

ChatGPT 安装步骤

需要工作区账户

在 设置 → 连接器 → 创建连接器 中，填写以下信息： | 变量 | 值 | |-----------|--------| | 名称 | Kash POS | | 描述 | 可记录目录中的销售并检索销售报告，实现 POS 软件集成。 | | MCP 服务器 URL | https://mcp.kash.click/mcp | | 身份验证 | oAuth |

添加后，该连接器将在 新对话中可用。

环境变量

| 变量 | 默认值 | 描述 | |-----------|----------|-------------| | APIKEY | ---- | 必需：你的 API 密钥 | | SHOPID | ---- | 必需：你的店铺 ID |

创建一个 .env 文件：

APIKEY=XXXXXXXXXXXXXX
SHOPID=XXX

▶️ 启动说明

HTTP 模式（可流式传输 MCP）

HTTP 模式需要 Redis 服务器。建议使用托管的 MCP HTTP/WebSocket 服务器 https://mcp.kash.click：

• POST https://mcp.kash.click/mcp：发送 JSON-RPC MCP 消息。
• GET https://mcp.kash.click/health：返回 { "status": "ok" }。
• GET https://mcp.kash.click/.well-known/mcp/manifest.json：获取 MCP 清单。

🔧 技术细节

🧪 可用的 MCP 工具（节选）

sale_create

创建一笔销售记录。

输入（Zod 模式，主要字段）：

• shopId: string, apiKey: string
• payment: number
• deliveryMethod: 0|1|2|3|4|5|6
• idUser?: number | string
• idClient?: number | string
• idtable?: number | string
• idcaisse?: number | string
• numcouverts?: number | string
• publicComment?: string
• privateComment?: string
• pagerNum?: number | string
• client?: {{ firstname?, lastname?, email?, phone?, address?, zip?, city?, country? }}
• `items: Array< {{ type:'catalog', productId?, quantity?, titleOverride?, priceOverride?, declinaisons? }} | {{ type:'dept', departmentId?, price?, title? }} | {{ type:'free', price?, title? }}

  `

旧版商品编码：

• 目录：productId_quantity_titleOverride_priceOverride_[...declinaisons]
• 部门销售：-<departmentId>_<price>_<title>
• 自由行：Free_<price>_<title> → 作为 itemsList[] 发送。

data_list_*（示例）

• data_list_products
• data_list_departments
• data_list_department_groups
• data_list_clients
• data_list_variations
• data_list_delivery_men
• data_list_payments
• data_list_cashboxes
• data_list_delivery_zones
• data_list_relay_points
• data_list_discounts
• data_list_users
• data_list_tables

所有这些工具都接受 {{ format=('json'|'csv'|'html') }} 参数。

📚 详细文档

兼容客户端

• ChatGPT (OpenAI)：通过外部 MCP 配置使用。
• Claude (Anthropic)：通过“工具清单 URL”使用。
• n8n / Flowise / LangChain：通过公共 URL 导入使用。

MCP 清单端点

MCP API 公开了一个 JSON 清单，描述了所有可供兼容客户端（ChatGPT、Claude、n8n 等）使用的工具。

公共清单 URL

https://mcp.kash.click/.well-known/mcp/manifest.json

🗂️ 配置服务器时，需将此 URL 提供给 MCP 客户端。

📄 许可证

© 2025. GNU 通用公共许可证