lightspeed-x-mcp

A Model Context Protocol server for Lightspeed X (Lightspeed Retail POS, the platform formerly known as Vend). It gives Claude, or any MCP client, read-only access to your store's sales, inventory, products, and customers, and it does the aggregation for you: revenue, units, COGS, gross profit, margin, discount, average basket value, and basket size, grouped by whatever dimension you ask for.

Read-only by construction. Every tool issues GET requests. There is no code path in this server that can create, update, or delete anything in your account, so you can point it at a live retail business without worrying about it.

"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

Why this exists

The Lightspeed X API is a survivor of the Vend era and it has some sharp edges that make naive clients either slow or quietly wrong. This server handles them so the model does not have to:

How the revenue math is derived

Verified against 200 consecutive live sales. Every one reconciled to the sale's own totals.price within two cents:

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

Three further checks on live data, all exact:

• Sum of per-day revenue over a week equals the week's grand total.

• An outlet's row in a group_by: outlet report equals the same report re-run with that outlet's server-side filter.

• The sum of amounts tendered by payment type equals revenue including tax.

Related MCP server: Shopify MCP Server

Install

Option 1: as a Claude Code plugin (recommended)

Three commands, no clone, no build, no paths to edit:

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

The third command runs a bundled setup skill that walks you through getting a token, writes it to the right place, and verifies the connection against your live account before telling you it worked.

The plugin also ships a reports skill so Claude knows which tool answers which kind of retail question, and how to read the numbers it gets back.

Credentials live at ${CLAUDE_PLUGIN_DATA}/credentials.env, a per-user directory that survives plugin updates. Nothing is shared between machines or teammates.

Note that /plugin uninstall deletes that directory, so an uninstall and reinstall means running setup again. The token itself stays live in Lightspeed regardless, so revoke it there if you are done with it.

Option 2: as a standalone MCP server

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

Requires Node 18 or newer.

Get an API token

In the Lightspeed X back office: Setup → Personal Tokens → Add Personal Token. Copy it before closing the dialog; it is shown once.

Two limits worth knowing before you plan a rollout:

• Only admin users can create personal tokens, and Lightspeed gates the feature to Plus plans. If Personal Tokens does not appear under Setup, someone with admin access has to create the token for you.

• Lightspeed does not offer read-only tokens. A token carries all permissions of the user who created it. This server only ever issues GET, but the token itself is a general-purpose credential, so treat it like a password and revoke it from the same screen if it leaks.

Check it works

npm run doctor

This validates your credentials, calls the live API, and names the exact cause of any failure. A wrong store domain and a bad token both return HTTP 401 from Lightspeed, so the doctor reports both possibilities rather than guessing.

Configure

Copy .env.example to .env and fill in your store:

LIGHTSPEED_DOMAIN=mystore
LIGHTSPEED_TOKEN=your_personal_token

LIGHTSPEED_DOMAIN accepts a bare prefix (mystore), a host (mystore.retail.lightspeed.app), or a full URL. All three resolve to the same place.

Multiple stores. Any LIGHTSPEED_<NAME>_DOMAIN + LIGHTSPEED_<NAME>_TOKEN pair defines an account named <name>, lowercased. Tools then take an optional account argument:

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

Values already present in the environment always beat the .env file, so a host that injects credentials directly takes precedence.

Register with Claude Code (standalone path only)

Skip this if you installed the plugin; the plugin registers the server itself.

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

Or add it to your config by hand:

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

For Claude Desktop, the same block goes in claude_desktop_config.json.

Verify it locally with the MCP Inspector:

npm run inspect

Tools

lightspeed_sales_report

The main event. Aggregates a date range and groups it.

| 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

Individual transactions, newest first, with optional line-item expansion. For drilling into one receipt, auditing a total, or looking at returns. Filters on outlet_id, customer_id, and min_total.

lightspeed_inventory_report

Stock on hand joined to product and outlet names, with retail and cost value of what is on the shelf.

status is the argument that matters:

group_by rolls up to product, outlet, category, brand, or supplier, which is how you answer "how much inventory value sits in each category".

lightspeed_search_products

Free-text search over name, variant name, SKU, and handle, with brand / supplier / category / tag filters. Matching runs locally against the cached catalog because the API's own search endpoint ranks poorly, so results are exact substring matches.

lightspeed_get_product

Full detail for one product by ID or exact SKU, including per-outlet stock and computed margin.

lightspeed_search_customers / lightspeed_get_customer

Look up customers by email (pushed to the API), or by name, phone, or customer code (matched locally). Returns the UUID the sales tools take as a customer_id filter. This returns personal data; handle it accordingly.

lightspeed_list_outlets / lightspeed_list_registers / lightspeed_list_accounts

Resolve store names to the outlet UUIDs the report filters take, list POS lanes including e-commerce registers, and see which accounts the server can reach. lightspeed_list_accounts never returns tokens.

lightspeed_list_reference_data

One tool over brands, suppliers, product_categories, tags, customer_groups, payment_types, promotions, taxes, and users. Use it to get the exact spelling of a brand or category before filtering a report on it.

lightspeed_api_get

Escape hatch for any endpoint without a purpose-built tool: /consignments, /price_books, /serial_numbers, and so on. Only GET is ever issued.

Performance and limits

Reports are shaped by the fact that sales cannot be filtered by date server side.

Most of a cold call is the ~30 single-row probes that locate the date range. Those probes are remembered per account, so the second report in a session usually needs none. Catalog, outlet, register, user, and inventory scans are cached for 15 minutes.

To keep things fast: pass outlet_id when you only care about one store, and prefer narrow date ranges. LIGHTSPEED_MAX_SALES (default 200,000) caps a single call, and the tool tells you plainly when it truncates rather than quietly returning a partial answer.

One honest caveat. Because the date range is found by version, a sale created before the range but edited after it can be missed. LIGHTSPEED_SEEK_MARGIN_DAYS (default 1) sets how far before the range the search aims, and raising it widens the safety net at the cost of scanning more records. This is inherent to an API that will not filter by date, not a shortcut taken here.

Configuration reference

Development

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

Tools return Markdown tables rather than raw JSON: a model reads an aligned table more reliably than a deep JSON blob, at a fraction of the tokens. The underlying numbers are also on structuredContent for programmatic callers.

Two conventions worth keeping if you contribute:

• Never throw from a tool handler. Failures are returned as isError results. The guard() wrapper enforces this.

• Never console.log. Stdout carries JSON-RPC frames. Diagnostics go to console.error.

Repository layout

.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/ is intentionally tracked in git, because Claude Code plugin installation does not run a build step and the compiled server has to ship with the repo. Run npm run build before committing a source change, and bump version in package.json, .claude-plugin/plugin.json, and .claude-plugin/marketplace.json together when releasing.

License

MIT. See LICENSE.

Not affiliated with or endorsed by Lightspeed Commerce.