Lightspeed X-Series MCP

Ask Claude about your Lightspeed Retail stores. Sales, stock, products and customers, through an MCP server that cannot write to your account.

Get started · What you can ask · Tools · Read-only · Hosting for a team · Security

Lightspeed Retail X-Series (formerly Vend) holds a store's whole day: every sale, every stock movement, every customer. This server puts that data in front of Claude, or any other MCP client, so you can ask a question in plain words and get the number back: "How did each store do yesterday?", "Where do we still have the large one in navy?", "Which promotions start next week?"

It is read-only in code. Lightspeed's personal tokens carry no scopes, so a token that can read your sales can also void them. This server never asks the API to change anything, and a test fails the build if a write ever creeps in.

What you can ask

Claude picks the tools; you just ask. Things that work well:

• Revenue: "Sales by outlet for last week, excluding tax." · "Daily takings in March as a table." · "Top 20 products by units this month."

• Stock: "How many of SKU 1234-NV are on hand, by store?" · "Show every size and color of the Weekender with stock per outlet." · "What's low at the warehouse?"

• Sales lookups: "Find invoice 10482." · "Which sales did Sam ring up on Saturday?" · "Show parked and on-account sales from this week."

• Customers and loyalty: "Look up jane@example.com: spend this year, store credit, address." · "Check gift card 6006 1234 5678."

• Merchandising: "Which promotions run this month and which products do they cover?" · "Prices in the wholesale price book for the Weekender."

• Operations: "Open stock transfers between stores." · "Purchase orders still waiting on delivery." · "Payments by type on register 2 today."

Dates are local store dates: "yesterday" means yesterday in the retailer's time zone, not UTC, and the server converts for you.

Related MCP server: VortexIQ MCP Connector

Features

• 35 tools covering sales, revenue summaries, products, variant families, inventory, transfers, purchase orders, customers, store credit, gift cards, promotions and price books, plus a guarded api_get for anything else.

• Answers, not just endpoints. sales_summary groups revenue by outlet, day, staff member or product in one call. search_products matches any mix of name, variant, SKU and barcode words. get_inventory rolls a whole variant family up into one stock table.

• Readable output. Outlet, staff and product ids come back with their names, and sales come back as compact rows unless you ask for the full object.

• Sized for a chat window. Variant families, price books and promotion product lists can run past a megabyte. Those tools return summaries by default, with full=True or a filter when you need everything.

• Local time done right. Date ranges are converted from the retailer's time zone to the UTC bounds the API wants, so day totals match the Lightspeed reports.

• Polite to the API. Reference data is cached (outlets and staff for an hour, the product catalog for 15 minutes), and a 429 is retried once after Retry-After.

• Standard library HTTP. The only dependency is the MCP SDK.

Get started

1. Make a personal token

In Lightspeed Retail, open Setup → Personal tokens and add one. Use an account that can see every outlet you want to query, because the token sees exactly what that user sees. Lightspeed lists personal tokens as a plan feature, so check your plan if the menu is missing.

Your domain prefix is the first part of your store address: mystore for mystore.retail.lightspeed.app.

2. Add it to your MCP client

The server runs over stdio. With uv installed, uvx fetches and runs it without a separate install step.

Claude Code

claude mcp add lightspeed \
  -e LIGHTSPEED_DOMAIN_PREFIX=mystore \
  -e LIGHTSPEED_TOKEN=your-token \
  -- uvx --from git+https://github.com/davidboulay/lightspeed-xseries-mcp lightspeed-xseries-mcp

Claude Desktop (claude_desktop_config.json), Cursor and other JSON-configured clients:

{
  "mcpServers": {
    "lightspeed": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/davidboulay/lightspeed-xseries-mcp", "lightspeed-xseries-mcp"],
      "env": {
        "LIGHTSPEED_DOMAIN_PREFIX": "mystore",
        "LIGHTSPEED_TOKEN": "your-token"
      }
    }
  }
}

Codex

codex mcp add lightspeed \
  --env LIGHTSPEED_DOMAIN_PREFIX=mystore --env LIGHTSPEED_TOKEN=your-token \
  -- uvx --from git+https://github.com/davidboulay/lightspeed-xseries-mcp lightspeed-xseries-mcp

Then ask "What's the retailer name and currency on Lightspeed?". If you get an answer, you're connected.

The token sits in your client's config file in plain text. That's normal for stdio MCP servers, but it means the file deserves the same care as the token. To share access without handing the token around, see Hosting for a team.

Several stores

One process serves one retailer account. For several, add the server once per store under different names (lightspeed-us, lightspeed-uk, …), each with its own prefix and token. Claude sees them as separate tool sets and can compare them.

Configuration

Tools

The ones to know:

• sales_summary: revenue for a local date range grouped by outlet, day, user, product or none, with totals excluding and including tax, the average sale and, per product, units. It counts closed sales by default, includes returns as negatives, and stops at 20,000 sales per call, setting truncated when you should narrow the range.

• search_products: every word must match somewhere in the name, variant, SKU or barcodes, so "navy large weekender" finds the right variant. Inactive products are hidden unless you ask.

• get_inventory: on-hand stock per outlet for one variant, or with include_variants=True for the whole family, totaled per variant.

Read-only by construction

A personal token can do anything its user can, including deleting products and voiding sales. So read-only can't be a setting. It has to be the code:

• Every tool sends GET. The two exceptions are /inventory and /inventory_levels, which are reads that take their filters as a POST body.

• There are no write tools. Every tool carries MCP's readOnlyHint, so clients that ask before running non-read tools never need to ask.

• api_get accepts plain resource paths only (no .., no query string in the path) and refuses integration plumbing that can carry credentials or partner data: /webhooks, /partner, /channel_requests, /security_events.

• tests/test_read_only.py parses the source and fails if any request uses a method other than GET or one of the two read-only POSTs. It also checks every tool's annotations and the api_get deny list. CI runs it on every push.

Read-only still means readable: whoever can call these tools can see customer contact details, staff names, and cost fields such as average cost and supplier price. Give access accordingly.

Hosting for a team

stdio keeps the token on one machine. To give colleagues access without giving them the token, run the server on a host you control behind an authenticating proxy that speaks remote MCP. For example, mcp-auth-proxy adds OAuth sign-in (Google, GitHub, …) with a domain allow-list:

mcp-auth-proxy --external-url https://lightspeed.example.com \
  --google-client-id … --google-client-secret … --google-allowed-workspaces example.com \
  -- lightspeed-xseries-mcp

People then add https://lightspeed.example.com/mcp as a custom connector (claude.ai → Settings → Connectors), sign in with their work account, and never see the token.

Never expose the server without authentication. Don't publish a bare HTTP port or a tunnel to it: anyone who finds the URL could read your sales and customers. Pin dependencies when you deploy. requirements.lock is a full, tested freeze.

API quirks it handles

Found against live data on API version 2026-10, and worth knowing if you call api_get yourself:

• Two sale shapes. /search?type=sales returns the older 2.x shape (total_price, total_tax, sale_date, outlet_id, line price_total), while /sales/{id} returns the date-based one (totals, source). The server reads both.

• Product names live on the family. Fetch products with includes[]=families. variant_name already contains the product name.

• Family stock. /inventory with variants: true wants the root product id and returns nothing for a variant id, so family stock goes through /inventory_levels with product_ids.

• /product_categories nests its list under data.categories.

• /promotions/search date filters mean "starts after". Use scope=current_upcoming for what's running now.

• Retailer settings. currency is an object (use currency.code), and the time zone may come back as timezone or time_zone.

Limitations

• Read-only, permanently. There's no plan to add writes. Use Lightspeed itself for changes.

• Personal tokens only. OAuth would need a registered Lightspeed developer app. A token is simpler for a single retailer, but it's tied to one user's access.

• Big ranges are capped. sales_summary stops at 20,000 sales and search_sales at its limit. Split long periods by month.

• Caches are per process. A product added in the last 15 minutes may not appear in search_products yet. get_product by SKU is always live.

• One 429 retry. Under heavy load a call can still fail with Lightspeed's rate-limit error. Ask again a moment later.

Project layout

src/lightspeed_xseries_mcp/
  server.py          the whole server: HTTP client, caches, 35 tools
tests/
  test_read_only.py  read-only guarantee, no network or token needed
requirements.lock    full tested dependency freeze, for deployments
docs/icon.svg

Development

git clone https://github.com/davidboulay/lightspeed-xseries-mcp.git && cd lightspeed-xseries-mcp
uv run --with-requirements requirements.lock --with-editable . python -m unittest discover -s tests -v

To try it against a real store, run it under the MCP Inspector:

LIGHTSPEED_DOMAIN_PREFIX=mystore LIGHTSPEED_TOKEN=… \
  npx @modelcontextprotocol/inspector uv run lightspeed-xseries-mcp

When you add a tool, keep it a read. The test will tell you if it isn't.

License

MIT. An independent project, not affiliated with or endorsed by Lightspeed Commerce Inc. "Lightspeed" and "X-Series" are its trademarks.