It is a read-only MCP server that gives you access to Lightspeed X retail data without any create/update/delete capabilities.
Sales reporting: aggregate revenue, units, COGS, gross profit, margin, discounts, tax, basket value/size, and customer counts by product, category, brand, outlet, day, hour, payment type, and more.
Transaction lookup: list individual sales with filters like outlet, customer, and minimum total, and expand line items for auditing.
Inventory reports: stock levels by status (low stock, reorder needed, out of stock, negative, in stock) with retail/cost value, rolled up by product, outlet, category, brand, or supplier.
Product search and detail: find products by free-text over name, SKU, variant, handle, plus filters and full product details with per-outlet stock and margin.
Customer lookup: search customers by email, name, phone, or code and retrieve details, returning IDs usable in sales filters.
Reference data: list brands, suppliers, categories, tags, customer groups, payment types, promotions, taxes, users, outlets, registers, and accounts.
API escape hatch: issue read-only GET requests to any Lightspeed X endpoint not covered by purpose-built tools.
Setup status: a dedicated tool reports credential health and the exact file path to fix missing configuration without exposing tokens.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@lightspeed-x What sold best yesterday?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_salesThe 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:
Reality | What this server does |
| Locates a date range by binary-searching the version sequence, then filters locally. A naive client that trusts the parameters returns wrong answers with total confidence. |
Pagination is version based, not cursor based. There is no | Handled transparently by the client's |
The documented max | Bulk scans use 5000 (sales use 1000, because sales carry their full line items). A 126,000-row inventory scan takes 26 requests instead of 630. |
Sale line items carry only | Joins against a cached product catalog so every report is human readable. |
A store's day does not start at UTC midnight, so a naive split files evening sales on the wrong day. | Day, month, weekday, and hour buckets are resolved in the outlet's own IANA timezone. |
Returns are booked as line items with negative quantity and negative totals. | They net out of every metric correctly, with no special casing needed. |
| Handled as its own case. It does return the complete taxonomy, so there is no need to rebuild the tree from products. |
On | Reads |
| Category filtering runs client side against the cached catalog, same as the date handling on |
Rate limit is | Exponential backoff with retries on 429 and 5xx. |
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.totalThree 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: Toast MCP Server
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:setupThe 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.
git clone https://github.com/genvjacobc/lightspeed-x-mcp.git
cd lightspeed-x-mcp
npm install
npm run buildRequires Node 18 or newer.
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.
npm run doctorThis 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.
Copy .env.example to .env and fill in your store:
LIGHTSPEED_DOMAIN=mystore
LIGHTSPEED_TOKEN=your_personal_tokenLIGHTSPEED_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=northValues already present in the environment always beat the .env file, so a host that injects credentials directly takes precedence.
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.jsOr 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 inspectlightspeed_sales_reportThe main event. Aggregates a date range and groups it.
Argument | Notes |
|
|
|
|
|
|
| Ranking controls |
| Applied server side, so it is genuinely fast |
| Defaults to |
| IANA zone override for day boundaries |
| 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_salesIndividual 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_reportStock 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:
Status | Meaning |
| Still sellable but at or below the reorder point. What is running low. |
| At or below the reorder point including zero and negative. The full buy list. |
| Exactly zero. |
| Below zero, which means a stock count error. |
| More than zero / everything. |
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_productsFree-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_productFull detail for one product by ID or exact SKU, including per-outlet stock and computed margin.
lightspeed_search_customers / lightspeed_get_customerLook 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_accountsResolve 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_dataOne 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_getEscape hatch for any endpoint without a purpose-built tool: /consignments, /price_books, /serial_numbers, and so on. Only GET is ever issued.
Reports are shaped by the fact that sales cannot be filtered by date server side.
Query | Typical cold time |
One day, all outlets (~900 sales) | 15 to 20s first call, then ~2s |
One week (~5,900 sales) | ~20s |
Full inventory scan (~126,000 rows) | ~25s first call, then instant |
Product / outlet / reference lookups | Under 1s after the first call |
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.
Variable | Default | Purpose |
| required | Store prefix, host, or URL |
| required | Personal token |
| optional | Additional named accounts |
| first account | Account used when a tool omits |
|
| API version path segment |
|
| Safety cap per sales call |
|
| Days of margin when seeking the version anchor |
| optional | Explicit path to a credential file. The plugin sets this to |
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 manifestssrc/
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 groupTools 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.
.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 builddist/ 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.
MIT. See LICENSE.
Not affiliated with or endorsed by Lightspeed Commerce.
Report whether this server has working Lightspeed credentials, and if not, the exact file path to create and what to put in it. Call this first when any Lightspeed tool fails with a credential error, when the user says Lightspeed is not connected, or when setting the server up for the first time. Safe to call at any time and never returns the token itself.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and openWorldHint=true, so the description need not restate safety labels. It adds valuable context: the tool never returns the token itself, and it reports the exact file path and content to create when credentials are absent. This is a useful disclosure beyond the structured hints, warranting a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, then usage conditions, then a safety note. Every word earns its place; there is no fluff or repeated information. Ideal conciseness for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, no output schema) and the description covers everything an agent needs to call it correctly: the exact condition to invoke it, what it reveals (success or failure plus remediation info), and its non-sensitive nature. Nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema is trivially covered at 100%, and the rubric sets a baseline of 4 for this case. The description adds no parameter-specific meaning, but nothing is missing—there is nothing to document. The baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement of what the tool does: report whether the server has working Lightspeed credentials and, if not, provide the exact file path and content to fix it. This is a specific verb-resource pair that leaves no doubt about the tool's role, and it stands alone clearly even without siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit, actionable usage guidance: call this first when a Lightspeed tool fails with a credential error, when the user reports Lightspeed is not connected, or during initial setup. It also notes the tool is safe to call at any time, covering both when to use and the absence of constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0lightspeed_setup_statusScored across 1 tool
With only one tool, there is no possibility of confusion or overlap between tool purposes. The tool's role as a credential/setup status check is clearly defined.
A single tool name cannot exhibit inconsistency. 'lightspeed_setup_status' is descriptive, snake_case, and follows a predictable pattern for this server.
A single setup/status tool is an extreme mismatch for a server named 'lightspeed-x'. The tool explicitly references other Lightspeed tools that do not exist, making the surface feel incomplete and unbalanced.
The server provides no actual Lightspeed operations—only a credential status check. This is severely incomplete for a Lightspeed integration domain and leaves agents with no way to perform real tasks.
Read-only zobrx e-commerce data: P&L, orders, inventory, marketplace, tax & shelf insights.
Read-only MCP over your own revenue and net margin across 14 billing rails
Read-only access to your VortexIQ store data: audits, KPIs, alerts, Brand DNA, reports, Ask VIQ.
Read-only Recharge store analytics: metrics, dimensions, and governed queries in plain language.
