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, access to your store's sales, inventory, products, customers, and consignments, 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 default. Every write needs your explicit approval. Out of the box the server registers no write tools at all. If you opt in (see Writes), Claude can prepare changes to products, tags, promotions, transfers, purchase orders, customers and more, but every write tool only previews. The one tool that actually sends a change, lightspeed_apply_write, asks you to approve each call, and in Claude Code that prompt appears even in auto mode, with no "always allow" option.
"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
"What transfers are still open?" → lightspeed_list_consignments
"Tag these 12 pouches pouchtype:nicotine" → lightspeed_update_product_tags (preview, then you approve)
"Archive the 6-pack promo" → lightspeed_archive_promotion (preview, then you approve)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:
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, users, price_books, and webhooks. Use it to get the exact spelling of a brand or category before filtering a report on it.
lightspeed_list_consignments / lightspeed_get_consignmentPurchase orders, store-to-store transfers, supplier returns and stocktakes. The list defaults to open work (OPEN, SENT, DISPATCHED). The detail view joins every line to the catalog and appends variant options, because on this endpoint product_sku is always null and variant names repeat the parent name, so four flavors of one product otherwise look like four identical rows. An unrecognised status filter is silently ignored by the API and returns the entire history, so status is an enum here and every row is re-checked client side.
lightspeed_get_balancesStore credit balance for a customer and balance/status of a gift card.
lightspeed_api_getEscape hatch for any endpoint without a purpose-built tool: /serial_numbers, /audit_log, and so on. Only GET is ever issued. (Fixed in 2.0: 1.x returned only metadata, because Claude Code shows structuredContent in place of the text block and the body was not in it.)
Writes are off unless you set LIGHTSPEED_WRITE_ACCOUNTS in the credentials file. With it unset, the server is exactly as read-only as 1.x: no write tool is even registered.
Every write is two steps, and only the second one can change your account.
Preview. A write tool such as lightspeed_update_product_tags reads current state, validates the request, and returns a before/after diff, the exact requests it would send, a plan id, and a confirm phrase like ARCHIVE PROMOTION "6-Pack Deal" ON genv #3F9A12BC. Nothing is sent.
Apply. lightspeed_apply_write takes the plan id and the confirm phrase. It is the only tool in the server that issues POST, PUT, PATCH or DELETE.
The gate on step 2:
Approval on every call. The tool carries _meta["anthropic/requiresUserInteraction"]: true. Claude Code then shows its permission prompt on every call, even in auto and bypassPermissions modes, offers no "don't ask again", ignores allow rules for it, and denies it outright in headless runs. In other MCP clients, the tool is marked destructiveHint and that client's own approval prompt applies.
The confirm phrase is written by the server. Claude has to echo it exactly, so the approval prompt you see says in plain words what will happen and on which account.
A server-authored dialog (MCP elicitation) shows the diff and asks you to tick "Apply this change" when the client supports it. Claude cannot alter that text. Declining blocks the write. Turn it off with LIGHTSPEED_WRITE_CONFIRM_DIALOG=false if the double confirmation is too much.
Plans are single use and expire after 15 minutes. A wrong confirm phrase discards the plan. A record that changed in Lightspeed since the preview makes the apply refuse.
Backups and audit. Before an update, the current record is saved to writes/backups/ next to the credentials file, and every applied write is appended to writes/audit.jsonl (request bodies and responses, never the token). lightspeed_revert_write previews an undo from the audit log, which then needs approval like any other write.
Safe retries. Writes run one at a time. A POST is retried only after a 429 (refused before processing), never after a timeout or 5xx, so a dropped connection cannot create a duplicate. If a multi-request plan fails partway, it stops and reports exactly what applied.
Sales, registers, store credit, gift cards and loyalty move money or change guest balances. They need a second switch, LIGHTSPEED_WRITE_HIGH_RISK=true, and the raw write tool treats those paths as high risk too.
Area | Tools |
Catalog |
|
Promotions |
|
Inventory |
|
Customers |
|
High risk |
|
Admin |
|
Gate |
|
Every preview says whether its endpoint has been exercised against a live account. Ones built only from Lightspeed's reference are labelled UNVERIFIED in the preview and the apply result, so you know to check the back office afterwards.
Learned from live probes and the reference, so you do not have to:
There is no "set on-hand to N". Deltas go through /stock_adjustments with a reason whose sign must match (DAMAGE is negative, STOCK_FOUND positive). Absolute counts are a STOCKTAKE consignment. Deliveries are a SUPPLIER consignment, which keeps cost history right.
Promotions are full-object updates (PUT /api/2.0/promotions/{id}, every field resent) and have no DELETE: archiving is a PUT with status: archived. The back office caps name at 30 characters and description at 70, but the API accepts longer and the UI then breaks, so the tool enforces it. start_time is store-local, despite the reference saying UTC. combinable_with_coupon defaults to true and loyalty_multiplier to 1, so create requires both explicitly.
Brands, suppliers, tags, customer groups, price books and webhooks update with PUT of the full object (PATCH returns "No route found"), so updates read the record and overlay your changes.
Product updates split into common (whole variant family) and details (one variant). tag_ids replaces the full list, which is why tag changes go through a merge tool.
Consignment line routes (/consignments/{id}/products/{product_id}) do not exist on API 2026-01, so consignment writes pin the dated 2026-07 version.
Sale voids must never be reversed, and a sale update with an incomplete line list deletes the missing lines. The sale tools only send the minimal state change.
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 |
| unset (read-only) | Comma-separated account keys allowed to write, or |
|
| Also allow sales, register, store credit, gift card and loyalty writes |
|
| Show the server-authored confirmation dialog when the client supports it |
| credentials folder | Where write backups and the audit log are kept |
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
skills/writes/ how to prepare, show and apply a write safely
src/tools/writes/ write previews and the apply/revert gate
src/lib/writes/ plan store, backups and audit log
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.
MerchantFlow is a hosted, read-only ecommerce analytics MCP server for Shopify and WooCommerce. It gives AI assistants tenant-scoped access to revenue, profit and loss, product and SKU profitability, COGS coverage, fulfillment costs, advertising spend, ROAS, marketing performance, cohorts, LTV, and business valuation across connected commerce and marketing platforms. Connect with OAuth over Streamable HTTP. No local server installation is required.
Read-only zobrx e-commerce data: P&L, orders, inventory, marketplace, tax & shelf insights.
Connect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.
Read-only Shopify and WooCommerce profit analytics: P&L, COGS, product margins, ROAS and LTV.
