Clover POS

clover-mcp

用于 Clover POS REST API 的 MCP 服务——为 AI 助手（Claude、Cursor 等）提供对 Clover 商户销售、库存、订单和客户数据的读取及安全写入权限。

状态： v0.7.0 已发布；当前工作树（未发布）——56 个工具、6 个提示词、支持两种身份验证模式，共 399 项测试。可在本地运行（stdio，单个商户），也可通过 HTTP 远程运行并使用 OAuth，支持单租户或多租户（参见 docs/DEPLOY.md）。端点契约已在沙盒中验证，详见 docs/endpoints.md。

⚠️ 独立项目——与 Clover Network, LLC 或 Fiserv, Inc. 无关联，未获其认可或赞助。“Clover” 是其各自所有者的商标，此处仅用于说明互操作性。本项目按 “现状” 提供，不附带任何保证——参见法律与免责声明。

功能

• 销售汇总、付款和退款报告
• 库存查询和低库存提醒
• 订单历史和未完成订单检查
• 客户搜索和创建
• 员工、班次、角色、类别、修饰项、税费、付款方式和设备查询；畅销商品
• 定价配置查询：折扣目录、小费建议预设、默认服务费
• 安全写入：更新商品价格、设置库存数量、创建客户／商品／类别／订单、添加订单项、更新客户、重命名商品、应用订单折扣、创建修饰项组／修饰项／标签
• AI 工具（通过客户端模型进行推理——服务端不持有大模型密钥）：销售简报、补货建议、异常检测、类别建议、客户消息草稿
• 预定义提示词工作流：每日简报、每周销售报告、库存健康检查、日终结算、客户查询、月度税务汇总

**无法执行的操作（设计如此）：**处理退款、收款、作废扣款、删除记录。这些操作只能在 Clover 控制面板中完成。

工具

工具	类型	说明
get_merchant_info / get_merchant_properties	读取	商户资料 + POS 配置（绝不返回银行字段）
get_sales_summary	读取	汇总时间范围（参见销售汇总语义）
get_sales_by_employee / get_tips_by_employee / get_sales_by_hour	读取	员工归属、小费分成和商户本地时段报告（PAYMENTS_R；员工姓名尽力提供）
list_payments / list_refunds / list_credits / list_tenders	读取	付款、退款、贷项、付款方式
list_orders / get_order / list_open_orders / list_order_types	读取	订单历史记录 + 详情
list_items / get_item / list_low_stock_items	读取	库存 + 库存量；get_item(include=[...]) 可选择获取 modifier_groups/tax_rates/categories/tags 关联详情
list_categories / list_modifiers / list_taxes / list_item_groups / list_attributes / list_tags / list_discounts	读取	商品目录结构
list_tip_suggestions / get_default_service_charge	读取	小费预设 + 服务费配置
list_devices / list_opening_hours / list_cash_events	读取	终端、营业时间、钱箱日志
get_top_items	读取	时间范围内按销量统计的畅销商品
list_employees / get_employee / list_shifts / list_active_shifts / list_roles	读取	绝不返回 PIN（EMPLOYEES_R）
search_customers / get_customer	读取	绝不返回卡片信息
whoami	读取	多租户身份诊断（不含机密信息）
summarize_sales / inventory_reorder_suggestions / detect_sales_anomalies / suggest_item_categories / draft_customer_message	AI	使用客户端模型进行推理；仅提供只读建议
create_customer / update_customer	写入	重复项检查 + dry_run；更新通过 elicitation 确认
create_item / create_category / create_order / add_line_item	写入	受保护：写入前执行 dry_run + 确认
set_item_price_cents / set_item_stock_quantity / update_item_name	写入	乐观锁预检查、边界校验、dry_run
apply_order_discount	写入	percentage / amount_cents / catalogue_discount_id 三者必须且只能提供一个；将正数 amount_cents 转为 Clover 要求的负数传输值；目录路径在客户端解析名称 + 数值；dry_run 预览包含客户端计算的行项目小计
create_modifier_group / create_modifier / create_tag	写入	重复项保护（组/标签）或父级预检查（修饰项）；受保护：写入前执行 dry_run + 确认

每个工具都带有 MCP 行为注解（readOnlyHint / destructiveHint / idempotentHint），以便客户端并行执行读取操作，并在写入前提示用户。

安装

已发布到 PyPI — 无需克隆：

uvx clover-mcp          # run directly (recommended)
# or
pip install clover-mcp  # then launch with: clover-mcp

从源代码安装（用于开发）：

git clone https://github.com/SBolivarLoL/clover-mcp-server
cd clover-mcp-server
uv pip install -e .

配置

将 .env.example 复制为 .env 并填写相应值：

cp .env.example .env

必需：

变量	说明
CLOVER_MERCHANT_ID	你的 Clover 商户 ID
CLOVER_ACCESS_TOKEN	你的 Clover API 访问令牌

可选：

变量	默认值	说明
CLOVER_REGION	na	na、eu 或 la
CLOVER_SANDBOX	false	使用 Clover 沙盒时设为 true
CLOVER_AUTH_MODE	token	token 或 oauth_refresh
CLOVER_READ_ONLY	false	在发出 Clover 请求前拒绝所有写入操作
CLOVER_WRITE_LIMIT_COUNT	10	每个安全时间窗口内的最大写入次数；0 表示禁用，负数将被拒绝
CLOVER_WRITE_LIMIT_WINDOW_S	300	写入安全时间窗口（秒），必须为正数

身份验证模式

• token — 粘贴静态访问令牌。适用于沙盒和单商户生产环境。如果令牌过期，请在 Clover Developer Dashboard 中重新生成。
• oauth_refresh — 服务器会在令牌过期时自动刷新，并将新的令牌对持久化到 CLOVER_TOKEN_STORE（默认值：~/.config/clover-mcp/tokens.json，模式 0600）。Clover 刷新令牌只能使用一次，因此每次刷新后都会写回轮换后的令牌对。运行 scripts/get_sandbox_token.py 获取令牌 — 该脚本会将令牌直接写入存储，因此你只需在 .env 中设置 CLOVER_AUTH_MODE、CLOVER_OAUTH_CLIENT_ID、CLOVER_OAUTH_CLIENT_SECRET 和 CLOVER_MERCHANT_ID（无需填写令牌值）。也可以选择将 CLOVER_ACCESS_TOKEN / CLOVER_REFRESH_TOKEN 粘贴到 .env 中。

使用遵循最小权限原则的令牌。 只授予实际使用的工具所需的权限范围（见下表）。只读部署完全不需要任何 *_W 范围。不要在沙盒和生产环境之间重复使用令牌。

Claude Desktop 配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "clover": {
      "command": "uvx",
      "args": ["clover-mcp"],
      "env": {
        "CLOVER_MERCHANT_ID": "your_merchant_id",
        "CLOVER_ACCESS_TOKEN": "your_token",
        "CLOVER_REGION": "na"
      }
    }
  }
}

Cursor 配置

添加到项目中的 .cursor/mcp.json（或全局配置 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "clover": {
      "command": "uvx",
      "args": ["clover-mcp"],
      "env": {
        "CLOVER_MERCHANT_ID": "your_merchant_id",
        "CLOVER_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

所需的 Clover 权限

你的令牌必须具有以下 Clover 权限范围：

权限	用于
MERCHANT_R	get_merchant_info
ORDERS_R	list_orders、get_order、list_open_orders
PAYMENTS_R	list_payments、list_refunds、list_credits、get_sales_summary、get_sales_by_employee、get_tips_by_employee、get_sales_by_hour
ORDERS_R	……也用于 get_top_items
INVENTORY_R	list_items、get_item、list_low_stock_items、list_categories、list_modifiers、list_taxes、list_discounts、list_item_groups、list_attributes、list_tags
INVENTORY_W	set_item_price_cents、set_item_stock_quantity、create_item、create_category、update_item_name、create_modifier_group、create_modifier、create_tag
ORDERS_W	create_order、add_line_item、apply_order_discount
CUSTOMERS_R	search_customers、get_customer
CUSTOMERS_W	create_customer、update_customer
EMPLOYEES_R	list_employees、get_employee、list_shifts、list_active_shifts、list_roles（可选）
MERCHANT_R	……也用于 list_devices、list_tenders、list_order_types、list_opening_hours、list_cash_events、list_tip_suggestions、get_default_service_charge

读取范围（*_R）会在启动时进行探测；服务器会对缺少的范围发出警告（不再退出 — 托管服务器仍必须启动），相关工具在调用时会返回 403。EMPLOYEES_R 是可选的。写入范围（*_W）不会进行探测（探测会修改数据）— 首次调用相关工具时，如果缺少写入范围，将返回 403。更改 Clover 应用的权限后，商户必须重新安装该应用。

远程 / 托管（v2）

默认情况下，该服务通过 stdio 在本地为单个商户运行。要将其作为远程服务运行：

• FastMCP Cloud / Horizon（最简单）： 使用入口点 server.py:mcp 进行部署， 启用平台内置身份验证，并设置单商户 Clover 环境变量。 平台会处理 OAuth、HTTPS 和传输 — 无需设置 IdP，且不要 设置 CLOVER_TRANSPORT/CLOVER_AUTH_*（该方式需要 IdP，否则会失败）。
• 自托管： 使用 server.py:create_server，使 clover-mcp 成为 OAuth 2.1 资源服务器（验证 IdP 的 JWT，按 RFC 9728 发布受保护资源 元数据，并按令牌声明进行路由），并且拒绝在缺少 IdP 时启动， 以避免以开放模式运行。

两种方式的完整设置说明见 docs/DEPLOY.md。SSO/SAML、SCIM、 审计和多租户授权的相关说明见：docs/enterprise-identity.md。

销售汇总口径

get_sales_summary 明确了会计口径，以便 LLM 进行说明：

• 总额 = result=SUCCESS 的付款金额总和。排除 FAIL、AUTH 和未捕获的 PRE_AUTH。
• 退款来自专用的 /refunds 端点（Clover 退款是金额为正数的独立对象，而不是负数付款）。作废根据已作废的付款统计。两者分别报告（refund_count/refund_amount、void_count），绝不会计入 payment_count。net_sales = gross_sales - refund_amount。
• 小费和税费分别列为独立项目。
• 服务费不单独报告：Clover 仅以百分比形式在订单中提供服务费（不提供计算后的金额），而客户实际支付的金额已通过付款总额计入 gross_sales。
• 离线付款也会纳入；如果时间范围内存在离线付款，note 会标记这一情况。
• 货币取自商户记录，不会使用默认值。
• 超过 90 天的时间范围会自动拆分并合并，过程透明。

开发

uv pip install -e ".[dev]"
pytest
ruff check src/ tests/ scripts/
ruff format --check src/ tests/ scripts/
mypy src/clover_mcp/

正确性评估和针对沙盒的延迟／负载基准测试： uv run python scripts/benchmark.py — 方法、结果和故障分析见 docs/eval.md。

架构（图表和模块映射）：docs/ARCHITECTURE.md。 运行 5 分钟演示：uv run python scripts/demo.py（或参阅 docs/DEMO.md 中的运行手册）。

可观测性

所有可观测性输出都写入 stderr（stdout 承载 MCP stdio 协议）。

• 审计日志（默认启用）——每次写入都会输出一行结构化 JSON： {"ts":"2026-07-02T…Z","audit":"write","method":"PUT","path":"/items/…","status":200,"merchant":"…"}。 UTC ts 记录时间；在多租户模式下，tenant 字段记录操作方。 不包含请求正文或密钥。使用 CLOVER_AUDIT_LOG=false 禁用。

• 延迟日志——设置 CLOVER_LATENCY_LOG=true，即可为每次 Clover HTTP 调用输出一行 latency_ms。

• 分布式追踪（可选）——安装 OpenTelemetry 扩展并将其指向你的收集器；每次 Clover 调用都会生成一个 span。未安装时，追踪是零开销的空操作（不添加依赖）：

  uv pip install -e ".[otel]"
  export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
  export OTEL_SERVICE_NAME=clover-mcp
  

安全

漏洞披露政策请参阅 SECURITY.md。

法律声明与免责声明

本内容不构成法律建议。以下说明阐述了本项目的宗旨及运营者的责任。

• 无关联关系。 这是一个独立的社区项目，与 Clover Network, LLC 或 Fiserv, Inc. 没有关联，也未获得其认可或赞助。“Clover”及相关标志是各自所有者的商标，在此仅作指称性使用，用于说明本软件可与 Clover REST API 互操作。本项目未使用 Clover 标志或品牌元素。
• 不提供担保／不承担责任。 本软件按 MIT License **“原样”**提供，不作任何形式的担保。对于因使用本软件而引发的任何索赔、损害或损失，作者概不负责，包括数据错误、意外写入、停机，或作者无法控制的 API 变更。
• 由你运营；你承担责任。 你使用自己的 Clover 账户和 API 凭据运行此服务。你须独自负责：遵守 Clover 的开发者／API 条款和商标使用政策；保护好你的令牌；并履行你所访问数据相关的数据保护（例如 GDPR/CCPA）及税务义务。写入工具会修改商户的实时数据——请先在沙盒中测试，并使用权限最小化的令牌。
• 不处理卡数据，不处理支付。 此服务不会处理支付卡数据（数据整形层会阻止此类数据），并且刻意不具备收款、退款或撤销交易的功能。它不是 PCI-DSS 解决方案。
• 第三方 API。 本项目仅使用运营者的凭据调用 Clover 的公共 REST API；不包含任何 Clover SDK 或专有代码。Clover 可随时更改或限制其 API，这可能导致功能无法正常使用。

许可证

MIT——请参阅 LICENSE。