lightspeed-x-mcp

一个用于 Lightspeed X（Lightspeed Retail POS，即前 Vend 平台）的 Model Context Protocol 服务器。它为 Claude 或任何 MCP 客户端提供对商店销售、库存、产品和客户的只读访问，并替你完成聚合计算：收入、件数、COGS、毛利润、毛利率、折扣、平均客单价和客单件数，可按你指定的任意维度分组。

构造上即只读。 每个工具都只发出 GET 请求。该服务器中不存在任何能创建、更新或删除账户中数据的代码路径，因此你可以放心地将其指向一个正在运营的零售业务。

"What sold best yesterday?"                → lightspeed_sales_report
"Revenue by store last week"               → lightspeed_sales_report, group_by: outlet
"Which SKUs need reordering?"              → lightspeed_inventory_report, status: reorder_needed
"What are our busiest hours?"              → lightspeed_sales_report, group_by: hour
"Margin by brand this month"               → lightspeed_sales_report, group_by: brand
"Pull up invoice 162220"                   → lightspeed_list_sales

为什么存在

Lightspeed X API 是 Vend 时代的遗留物，它有一些尖锐的边角，会让天真的客户端要么变慢、要么悄悄出错。这个服务器替你处理了这些问题，让模型不必操心：

收入计算方式如何推导

已对照 200 笔连续的实时销售进行验证。每一笔都能与销售自身的 totals.price 在两美分以内对账：

line revenue excl tax = line_items[].pricing.total        (net of discount, already x quantity)
line COGS             = line_items[].pricing.cost_total
line discount given   = line_items[].pricing.discount_total
line tax              = line_items[].tax.total

对实时数据还有三项进一步检查，全部精确匹配：

• 一周内按日收入之和等于该周总计。

• group_by: outlet 报表中某门店的行，等于用该门店的服务端过滤器重新运行同一报表的结果。

• 按支付方式统计的实收金额之和等于含税收入。

Related MCP server: mcp-pdv-demo

安装

选项 1：作为 Claude Code 插件（推荐）

三条命令，无需克隆、无需构建、无需编辑路径：

/plugin marketplace add genvjacobc/lightspeed-x-mcp
/plugin install lightspeed-x@lightspeed-x-mcp
/lightspeed-x:setup

第三条命令运行一个内置的设置技能，引导你获取令牌、将其写入正确位置，并在告诉你成功之前对照你的实时账户验证连接。

该插件还附带一个 reports 技能，让 Claude 知道哪个工具回答哪类零售问题，以及如何解读拿到的数字。

凭据存放在 ${CLAUDE_PLUGIN_DATA}/credentials.env，这是一个按用户隔离的目录，插件更新后依然保留。任何内容都不会在机器或团队成员之间共享。

注意，/plugin uninstall 会删除该目录，因此卸载后重新安装意味着需要重新运行设置。令牌本身在 Lightspeed 中仍然有效，所以如果你不再需要它，请在那里撤销。

选项 2：作为独立 MCP 服务器

git clone https://github.com/genvjacobc/lightspeed-x-mcp.git
cd lightspeed-x-mcp
npm install
npm run build

需要 Node 18 或更高版本。

获取 API 令牌

在 Lightspeed X 后台：Setup → Personal Tokens → Add Personal Token。在关闭对话框之前复制它；它只显示一次。

在规划部署之前，有两个限制值得了解：

• 只有管理员用户才能创建个人令牌，而且 Lightspeed 将该功能限制在 Plus 套餐。 如果 Setup 下没有出现 Personal Tokens，则需要有管理员权限的人为你创建令牌。

• Lightspeed 不提供只读令牌。 令牌携带创建它的用户的全部权限。这个服务器只发出 GET 请求，但令牌本身是通用凭据，所以要像对待密码一样对待它；如果泄露，请在同一界面撤销。

验证是否可用

npm run doctor

这会验证你的凭据、调用实时 API，并明确指出任何失败的确切原因。错误的商店域名和错误的令牌都会从 Lightspeed 返回 HTTP 401，因此诊断工具会同时报告两种可能性，而不是猜测。

配置

将 .env.example 复制为 .env 并填写你的商店信息：

LIGHTSPEED_DOMAIN=mystore
LIGHTSPEED_TOKEN=your_personal_token

LIGHTSPEED_DOMAIN 接受裸前缀（mystore）、主机名（mystore.retail.lightspeed.app）或完整 URL。三者都解析到同一位置。

多商店。 任意 LIGHTSPEED_<NAME>_DOMAIN + LIGHTSPEED_<NAME>_TOKEN 组合定义一个名为 <name>（小写）的账户。工具随后接受一个可选的 account 参数：

LIGHTSPEED_NORTH_DOMAIN=northstore
LIGHTSPEED_NORTH_TOKEN=token_for_north
LIGHTSPEED_SOUTH_DOMAIN=southstore
LIGHTSPEED_SOUTH_TOKEN=token_for_south
LIGHTSPEED_DEFAULT_ACCOUNT=north

环境中已有的值始终优先于 .env 文件，因此直接注入凭据的主机具有更高优先级。

注册到 Claude Code（仅限独立路径）

如果你安装了插件，请跳过此步骤；插件会自行注册服务器。

claude mcp add lightspeed-x -s user -- node /absolute/path/to/lightspeed-x-mcp/dist/index.js

或者手动将其添加到你的配置中：

{
  "mcpServers": {
    "lightspeed-x": {
      "command": "node",
      "args": ["/absolute/path/to/lightspeed-x-mcp/dist/index.js"],
      "env": {
        "LIGHTSPEED_DOMAIN": "mystore",
        "LIGHTSPEED_TOKEN": "your_personal_token"
      }
    }
  }
}

对于 Claude Desktop，同样的配置块放在 claude_desktop_config.json 中。

使用 MCP Inspector 在本地验证：

npm run inspect

工具

lightspeed_sales_report

主菜。聚合一个日期范围并对其分组。

| Outlet          |   Revenue | Units | Sales | Basket value | Gross profit | Margin |
| --------------- | --------: | ----: | ----: | -----------: | -----------: | -----: |
| South Lincoln   | $3,401.60 |   193 |    91 |       $37.38 |    $2,342.35 |  68.9% |
| York            | $3,222.86 | 159.2 |    73 |       $44.15 |    $2,238.77 |  69.5% |

lightspeed_list_sales

单笔交易，最新在前，可选展开行项目。用于深入查看一张小票、审计某个总额或查看退货。支持按 outlet_id、customer_id 和 min_total 过滤。

lightspeed_inventory_report

现有库存与商品和门店名称连接，并给出货架上的零售价值和成本价值。

status 是关键参数：

group_by 可汇总到 product、outlet、category、brand 或 supplier，这就是回答"每个类别中有多少库存价值"的方式。

lightspeed_search_products

对名称、变体名称、SKU 和 handle 进行自由文本搜索，支持品牌 / 供应商 / 类别 / 标签过滤。匹配在本地针对缓存的目录进行，因为 API 自身的搜索端点排序效果不佳，因此结果是精确的子串匹配。

lightspeed_get_product

按 ID 或精确 SKU 获取单个商品的完整详情，包括各门店库存和计算出的毛利率。

lightspeed_search_customers / lightspeed_get_customer

按邮箱（推送到 API）或按姓名、电话、客户代码（本地匹配）查找客户。返回销售工具用作 customer_id 过滤条件的 UUID。这会返回个人数据，请妥善处理。

lightspeed_list_outlets / lightspeed_list_registers / lightspeed_list_accounts

将商店名称解析为报表过滤器所需的门店 UUID，列出包括电商收银机在内的 POS 通道，并查看服务器可以访问哪些账户。lightspeed_list_accounts 永远不会返回令牌。

lightspeed_list_reference_data

一个工具涵盖 brands、suppliers、product_categories、tags、customer_groups、payment_types、promotions、taxes 和 users。在按品牌或类别筛选报表之前，使用它来获取品牌或类别的确切拼写。

lightspeed_api_get

适用于任何没有专用工具的端点的逃生舱：/consignments、/price_books、/serial_numbers 等。仅会发出 GET 请求。

性能与限制

报表的形态受限于销售记录无法在服务端按日期过滤这一事实。

冷调用的大部分时间花在大约 30 次单行探测上，用于定位日期范围。这些探测会按账户记住，因此会话中的第二份报表通常无需任何探测。目录、门店、收银机、用户和库存扫描会缓存 15 分钟。

为了保持快速运行：当您只关心单个门店时，请传入 outlet_id，并优先选择较窄的日期范围。LIGHTSPEED_MAX_SALES（默认 200,000）限制单次调用的上限，工具在截断时会明确告知，而不会静默返回不完整的答案。

一个坦诚的注意事项。 由于日期范围是通过版本查找的，因此在范围之前创建但在范围之后编辑的销售记录可能会被遗漏。LIGHTSPEED_SEEK_MARGIN_DAYS（默认 1）设定搜索在范围之前的目标距离，提高该值会扩大安全网，代价是扫描更多记录。这是不改按日期过滤的 API 所固有的特性，而非此处采用的捷径。

配置参考

开发

npm run dev      # run from source with tsx
npm run build    # compile to dist/
npm run inspect  # MCP Inspector against the built server
npm run doctor   # credentials + live connectivity check
npm run validate-plugin  # validate the plugin manifests

src/
  index.ts            entry point, env loading, tool registration
  config.ts           account discovery from the environment
  lib/
    client.ts         HTTP client, retry, version pagination
    version-seek.ts   date to version binary search
    sales.ts          sale fetching and metric aggregation
    catalog.ts        cached product, outlet, register, inventory lookups
    time.ts           timezone-aware day boundaries
    format.ts         Markdown table rendering, tool results
  tools/              one file per tool group

工具返回 Markdown 表格而非原始 JSON：模型阅读对齐的表格比深层 JSON 块更可靠，且所需 token 更少。底层数字也可通过 structuredContent 供程序化调用者使用。

如果你参与贡献，值得遵守两条约定：

• 绝不从工具处理程序中抛出异常。 失败通过 isError 结果返回。guard() 包装器强制执行这一点。

• 绝不使用 console.log。 标准输出承载着 JSON-RPC 帧。诊断信息请使用 console.error。

仓库结构

.claude-plugin/     plugin + marketplace manifests
.mcp.json           MCP server declaration used by the plugin path
skills/setup/       guided connection walkthrough
skills/reports/     how to answer retail questions with these tools
src/                TypeScript source
dist/               compiled output, committed so plugin installs need no build

dist/ 有意被纳入 git 跟踪，因为 Claude Code 插件安装不执行构建步骤，编译后的服务器必须随仓库一起发布。提交源代码更改前请运行 npm run build，并在发布时一并提升 package.json、.claude-plugin/plugin.json 和 .claude-plugin/marketplace.json 中的 version。

许可证

MIT。参见 LICENSE。

与 Lightspeed Commerce 无关联，亦未获得其认可。