lightspeed-x-mcp

Model Context Protocol サーバーであり、Lightspeed X（旧Vendとして知られるプラットフォーム、Lightspeed Retail POS）向けです。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 に2セント以内で一致しました:

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

さらに、実データでの3つの検証も完全一致です:

• 1週間の1日ごとの売上の合計が、その週の総計と一致する。

• group_by: outlet レポートの店舗の行が、その店舗のサーバーサイドフィルタで再実行した同じレポートと一致する。

• 支払い種別ごとの支払い額の合計が、税込み売上と一致する。

Related MCP server: mcp-pdv-demo

インストール

オプション1: Claude Codeプラグインとして（推奨）

わずか3つのコマンドで、クローン不要、ビルド不要、編集するパスも不要です:

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

3つ目のコマンドは、同梱されたセットアップスキルを実行します。このスキルは、トークンの取得を支援し、正しい場所に書き込み、ライブアカウントとの接続を検証してから、動作したことを通知します。

また、プラグインには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。ダイアログを閉じる前にコピーしてください。一度だけ表示されます。

ロールアウトを計画する前に知っておくべき2つの制限があります:

• 管理者ユーザーのみがパーソナルトークンを作成でき、Lightspeedはこの機能をPlusプランに限定しています。 Setupの下にPersonal Tokensが表示されない場合、管理者アクセス権を持つ誰かがあなたの代わりにトークンを作成する必要があります。

• Lightspeedは読み取り専用トークンを提供していません。 トークンは、作成したユーザーのすべての権限保持します。このサーバーは常に GET のみを発行しますが、トークン自体は汎用のvinfidential情報です。そのため、パスワードのように密に取り扱い、漏洩した場合は同じ画面で失効させてください。

動作確認

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を受け入れます。3つともすべて同じ場所に解決されます。

複数のストア。 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

個別の取引を新しい順に返し（オプションで行アイテムを展開）、1件のレシートへのド派ノ、合計の監査、返品の確認に使用します。outlet_id、customer_id、min_total でフィルタリングします。

lightspeed_inventory_report

手持ち在庫を、商品名と店舗名に結合し、棚にあるものの小売価値と原価価値を表示します。

重要になるのは status 引数です:

group_by は product、outlet、category、brand、supplier に展開できます。これにより、「各カテゴリにどれくらいの在庫価値があるか」という質問に答えます。

lightspeed_search_products

名前、バリアント名、SKU、ハンドルを対象にしたフリーテキスト検索で、ブランド / サプライヤ / カテゴリ / タグのフィルタが付いています。APIの検索エンドポイントは検索品質が低いため、キャッシュされたカタログに対してローカルで正確な部分文字列一致を行います。

lightspeed_get_product

IDまたは完全一致のSKUで、1つの商品の詳細を返します。店舗ごとの在庫と起算済みマージンさあらため含みます。

lightspeed_search_customers / lightspeed_get_customer

メールアドレス（APIに送信）、または名前・電話番号・顧客コード（問い合わせコード）で顧客を検索します。販売ツールが customer_id フィルタとして受け取るUUIDを返します。このツールは個人データを返します。それに応じて取り扱ってください。

lightspeed_list_outlets / lightspeed_list_registers / lightspeed_list_accounts

ストア名を、レポートフィルたが受け取る店舗UUIDに変換します。POSレーンを（eコマースレジスタ含む）一覧表示し、サーバーが到達できるアカウントを確認します。lightspeed_list_accounts がトークンを返すことはありません。

lightspeed_list_reference_data

brands、suppliers、product_categories、tags、customer_groups、payment_types、promotions、taxes、users をまとめて扱う 1 つのツールです。レポートを絞り込む前に、ブランドやカテゴリの正確なスペルを確認するために使用します。

lightspeed_api_get

専用ツールがない任意のエンドポイントのための脱出ハッチです: /consignments、/price_books、/serial_numbers など。送信されるのは GET のみです。

パフォーマンスと制限

売上はサーバー側で日付によるフィルタリングができないため、レポートはその影響を受けます。

初回呼び出しの大部分は、日付範囲を特定するための約 30 回の単一行プローブです。このプローブはアカウントごとに記憶されるため、セッション内の 2 回目以降のレポートでは通常不要です。カタログ、店舗、レジ、ユーザー、在庫のスキャンは 15 分間キャッシュされます。

高速に保つには: 1 つの店舗だけを対象にする場合は outlet_id を渡し、日付範囲は狭めにしてください。LIGHTSPEED_MAX_SALES(デフォルト 200,000)は 1 回の呼び出しの上限を設定し、ツールは結果を切り詰めた場合、黙って不完全な回答を返すのではなく、その旨を明確に伝えます。

正直な注意点。 日付範囲はバージョンによって特定されるため、範囲より前に作成され、範囲より後に編集された売上は見落とされる可能性があります。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

ツールは未焼成の JSON ではなく Markdown テーブルを返します。モデルは深く入れ子になった JSON のブロックよりも、整理されたテーブルの方が確実に読み取れ、トークン消費も抑えられます。基になる数値は、プログラムから呼び出す向利用者向けに structuredContent にも格納されます。

貢献する際に守る価値のある 2 つの慣習があります:

• ツールハンドラーから例外を投げない。 失敗は 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。ライセンスは ライセンス を参照してください。

Lightspeed Commerce とは提携していませんし、その推奨も受けていません。