This server lets Claude read and write your Loyverse point-of-sale data through MCP, covering account info, catalogue, stock, customers, sales, and reporting.
Account & operations: view merchant profile, stores, employees, shifts, POS devices, payment types, and suppliers.
Catalogue management: create, update, list, and delete items, variants, categories, modifiers, discounts, and taxes; set item images.
Inventory: read stock levels per store/variant and set absolute stock levels.
Customers: list, fetch, create, and update loyalty customers with points and visit data.
Sales & receipts: list, fetch, create, and refund receipts.
Reporting: generate sales summaries by day, item, category, payment type, employee, or store over a date range.
Integration: list and create webhook subscriptions.
Safety features: read-only tools are marked, destructive tools are flagged, and the server handles pagination, retries, and plain-language errors.
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., "@Loyverse MCP Server What were my top five selling items last week?"
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.
Connect Claude to your Loyverse point-of-sale account. An open-source Model Context Protocol (MCP) server that gives Claude Desktop, Claude Code and any other MCP client read and write access to your Loyverse catalogue, inventory, customers, receipts and sales reports.
Ask questions about your shop in plain English and get answers from live till data, or have Claude update your catalogue and stock for you. Install it as a one-click Claude Desktop extension, or run it from source in any MCP client.
Built against the published Loyverse API v1.0 reference. Every read tool in this repository has been run against a live Loyverse account.
Once connected, these all work without you touching the Loyverse back office:
Sales reporting. "What were my top five selling dishes last week, and how much did each bring in?" or "Compare cash against card takings for the last fortnight."
Stock checks. "Which items are down to fewer than three in stock at my main store?"
Catalogue edits. "Add a new item called Mango Lassi at £3.50 in the Drinks category, then set its opening stock to 40."
Reconciliation. "Show me every shift that closed more than £5 away from the expected cash."
Customer lookups. "Which loyalty customers have not visited in 60 days?"
Related MCP server: mcploy
The Loyverse API returns raw receipts. Answering "what sold best last week" from those means paging through hundreds of records, which is slow and burns a lot of context.
This server adds loyverse_sales_summary, a tool the API does not provide. It
aggregates a date range into totals and a ranked breakdown by day, item, category,
payment type, employee or store, in a single call. Everything else maps closely to the
underlying API so nothing is hidden from you.
Twenty-six read tools and fifteen write tools across the whole documented API surface.
Area | Tools |
Account | merchant profile, stores, employees, shifts, POS devices, payment types, suppliers |
Catalogue | items, variants, categories, modifiers, discounts, taxes |
Stock | inventory levels, absolute stock setting |
Customers | loyalty customers, visits, points |
Sales | receipts, receipt creation, refunds |
Reporting | sales summary by day, item, category, payment type, employee or store |
Integration | webhook subscriptions |
Also included: cursor pagination handled for you, automatic retry with backoff against the API rate limit, and errors translated into plain sentences rather than bare status codes.
Node.js 20 or newer, for the from-source install only
A Loyverse account and an access token
In the Loyverse back office, go to Settings > Access tokens, add a token, and copy it. The token grants full access to the account, so treat it as a password. If a token is ever exposed, delete it in the same screen and issue a new one.
The quickest route, and nothing to build. Download loyverse.mcpb from the
releases page, then drag it onto
Claude Desktop's extensions settings. Claude asks for your access token on install and
stores it as a sensitive value. The bundle carries the whole server in one file and has
no node_modules to install.
To build the bundle yourself:
npm install && npm run bundleThat produces loyverse.mcpb at the repository root.
The desktop extension is a local process, so it only works in Claude Desktop. Claude on the web and on iOS and Android cannot run local servers; they reach a remote MCP server from Anthropic's cloud instead. This repository ships that too.
The hosted server signs merchants in through Loyverse's own OAuth, so it never sees a Loyverse password and never hands a Loyverse token to Claude. It issues its own tokens, which can be revoked by disconnecting the connector.
It offers two scopes, and the difference is enforced rather than advisory:
Scope | What Claude gets |
| The 26 read tools. The 15 write tools are not listed at all. |
| All 41 tools. |
Read is the default when a client asks for nothing, and a refresh can narrow scope but never widen it. Granting read-only is a good idea on a phone: it is the difference between Claude being unable to refund a receipt and merely being asked not to.
npm install && npm run db:push && npm run dev:remoteIt needs a Postgres database and a Loyverse OAuth app. Copy .env.remote.example to
.env.remote and fill in:
Variable | Purpose |
| The origin the server is reachable at, with no trailing slash |
| Postgres connection string |
| Encrypts the Loyverse tokens at rest. |
| |
| From the same place |
The Loyverse app's redirect URI must be exactly <PUBLIC_URL>/callback.
Deployment targets Vercel: vercel.json routes every path to one function, and the
whole OAuth surface plus the MCP endpoint run inside it. Add the connector in Claude
using <PUBLIC_URL>/mcp.
Tokens this server issues are stored only as SHA-256 hashes, so a database leak cannot be replayed against it. The Loyverse tokens it holds on a merchant's behalf have to be usable, so those are encrypted with AES-256-GCM under a key that lives in the environment rather than the database. Authorization codes are single use, and redeeming one twice revokes the entire grant on the assumption the first redemption was stolen.
npm install && npm run buildThen add the server to your MCP client's configuration. For Claude Desktop, edit
claude_desktop_config.json:
{
"mcpServers": {
"loyverse": {
"command": "node",
"args": ["/absolute/path/to/loyverse-mcp/dist/index.js"],
"env": { "LOYVERSE_ACCESS_TOKEN": "your-token-here" }
}
}
}For local development, copy .env.example to .env, put the token there and run
npm run dev. The .env file is gitignored and must stay that way.
Variable | Required | Default | Purpose |
| yes | — | Loyverse access token |
| no |
| Override the API host |
| no |
| Per-request timeout |
These are limits of the upstream API, not of this server. The tools report them as plain sentences rather than bare status codes.
Sales history stops at 31 days. Older ranges return 402 unless the account has
the Unlimited Sales History add-on.
Rate limit is 300 requests per 300 seconds. The client retries a 429 with
exponential backoff, three times by default.
Stock is absolute, not a delta. loyverse_set_inventory takes stock_after, the
level to leave in place. Read the current level first if you mean to add or remove.
A receipt created through the API carries one payment type. Split tender is rejected before the request is sent.
Updates use POST, not PUT. Passing an existing id to an upsert tool updates that record.
Pages cap at 250 objects. The client follows cursors for you and tells you when a result was truncated.
Tools are annotated so a client can tell them apart:
Twenty-six tools are readOnlyHint and change nothing.
loyverse_set_inventory, loyverse_refund_receipt and loyverse_delete are
destructiveHint. They overwrite stock, move money and remove records, and none of
it can be undone through the API.
The remaining write tools create or update records and are idempotent when given an id.
The server instructions tell the model to state what will change and get agreement before calling any tool that writes.
npm test # unit tests, no network
npm run typecheck
npm run smoke # every read-only tool against the live account in .envnpm run smoke never calls a write tool.
Is this an official Loyverse integration? No. It is an independent open-source project, not built, endorsed or supported by Loyverse.
Do I need a paid Loyverse plan? No. The only paid feature that matters here is Unlimited Sales History, without which the API serves the last 31 days of receipts.
Which MCP clients does it work with?
Any of them, since it speaks MCP over stdio. It has been tested end to end in Claude
Desktop as a .mcpb extension, and the from-source build has been driven directly over
stdio. The desktop extension is the easiest route.
Is my sales data sent anywhere?
No. Requests go only to api.loyverse.com. The server has no database, no logging and
no analytics. See the Privacy Policy below.
Can it change or delete my data? Yes. Fifteen of the forty-one tools write, and three of those are irreversible. They are annotated so your client can warn you, but treat the access token as full account access, because that is what Loyverse gives it.
Does it support more than one store?
Yes. Tools that make sense per store take a store_id, and the sales summary can group
by store.
Does it support Loyverse OAuth instead of an access token? Not yet. OAuth is needed for a hosted, multi-tenant deployment and is planned. The client is already written to take a token per session, so it is a transport change rather than a rewrite.
This server is a local client for an API you already have an account with. It stores no data of its own.
What it collects. Nothing. The server keeps no database, no log file and no analytics.
What it transmits. Requests go only to api.loyverse.com over HTTPS, carrying
your access token and the arguments of the tool you called. Responses are returned to
your MCP client and held only in memory for the duration of the call.
Third parties. None, other than Loyverse itself. Data handling on their side is governed by the Loyverse privacy policy.
Personal data. The customer tools read and write names, emails, phone numbers and addresses that live in your Loyverse account. This server passes them through and retains nothing.
Retention. No data is retained after a tool call returns.
Your token. Read from the environment at startup and held in memory only. It is never written to disk by this server and never sent anywhere but Loyverse.
Contact. Raise an issue on this repository.
This is an independent, unofficial project. It is not built, endorsed or supported by Loyverse. "Loyverse" is a trademark of its owner.
MIT. See LICENSE.
Record a sale. This posts a real transaction to the merchant's books and affects stock and reporting, so confirm the line items and total with the user before calling it. A receipt created through the API can carry only one payment type; split tender is not supported.
Inputs: payments (required), line_items (required), note, order, +6 more.
Subscribe an https endpoint to a Loyverse event. The endpoint will receive the merchant's live business data, so only register a URL the user has given you.
Inputs: url (required), type (required), status.
Delete one record from the merchant's Loyverse account. This removes live business data and cannot be undone through the API. Name the record back to the user and get an explicit yes before calling it. Deleting an item also removes its variants and their stock history.
Inputs: id (required), resource (required).
Fetch one customer by id, including loyalty points and visit history totals.
Inputs: customer_id (required).
Fetch one employee by id.
Inputs: employee_id (required).
Read current stock per variant per store. Filter by store_ids or variant_ids to keep the result small.
Inputs: limit, store_ids, variant_ids, updated_at_max, +1 more.
Fetch one catalogue item by id, including all of its variants.
Inputs: item_id (required).
Fetch the account profile: business name, country, and the currency with its decimal places. Call this first to know how to format money in every other result.
Inputs: no named parameters.
Fetch one receipt by its receipt number.
Inputs: receipt_number (required).
Fetch one shift by id.
Inputs: shift_id (required).
Fetch one store by id.
Inputs: store_id (required).
Fetch one supplier by id.
Inputs: supplier_id (required).
Fetch one variant by id, including its per-store pricing.
Inputs: variant_id (required).
List item categories.
Inputs: limit, show_deleted, categories_ids.
List loyalty customers with visit counts, total spend and points balance. Filter by email to find one person.
Inputs: email, limit, customer_ids, created_at_max, +3 more.
List the discounts configured on the account.
Inputs: discount_ids, show_deleted, created_at_max, created_at_min, +2 more.
List employees and their roles. Receipts and shifts reference employees by id.
Inputs: limit, employee_ids, show_deleted, created_at_max, +3 more.
List catalogue items with their variants, prices and SKUs. Use this to find the variant_id that the inventory and receipt tools need.
Inputs: limit, items_ids, show_deleted, created_at_max, +3 more.
List modifier groups and their options, such as sizes or extras.
Inputs: limit, modifier_ids, show_deleted, created_at_max, +3 more.
List the payment types configured on the account. Creating a receipt requires a payment_type_id from here.
Inputs: show_deleted, created_at_max, created_at_min, updated_at_max, +2 more.
List the till devices registered to the account.
Inputs: store_id, show_deleted.
List sales and refund receipts with their line items, taxes, discounts and payments. Without the Unlimited Sales History add-on the account only serves the last 31 days, and older ranges return a payment-required error.
Inputs: limit, order, source, store_id, +7 more.
List till shifts with their opening and closing cash amounts. Use this to reconcile a day's cash drawer.
Inputs: limit, store_ids, created_at_max, created_at_min.
List the stores on the account with their addresses. Most filters elsewhere take a store_id from here.
Inputs: store_ids, show_deleted.
List suppliers with their contact details.
Inputs: limit, show_deleted, suppliers_ids.
List tax rates and whether each is included in or added to the price.
Inputs: tax_ids, show_deleted, created_at_max, created_at_min, +2 more.
List item variants, optionally filtered by SKU or parent item. A variant is the sellable unit that inventory and receipts refer to.
Inputs: sku, limit, items_ids, show_deleted, +5 more.
List the webhook subscriptions registered on the account.
Inputs: no named parameters.
Issue a refund against an existing receipt, in full or for named line items. This moves money and restores stock, and it cannot be undone through the API. Always confirm the receipt number, the lines and the quantities with the user first.
Inputs: line_items (required), receipt_number (required), source, store_id, +2 more.
Aggregate receipts over a date range into totals and a breakdown, without the model having to page through raw receipts. Reports gross sales, refunds, discounts, tax, tips and net, plus a ranked breakdown by day, item, category, payment type, employee or store. Cancelled receipts are excluded. Without the Unlimited Sales History add-on the account only serves the last 31 days.
Inputs: created_at_max (required), created_at_min (required), top, group_by, +2 more.
Set stock to an absolute figure for one or more variants at a store. stock_after is the resulting stock level, not a delta: sending 5 leaves 5 in stock regardless of what was there before. Read the current level with loyverse_get_inventory first if you mean to add or remove a quantity.
Inputs: inventory_levels (required).
Attach an image to a catalogue item from a public URL, replacing any existing one.
Inputs: item_id (required), image_url (required).
Create a category, or rename one by passing its id.
Inputs: name (required), id, color.
Create a customer, or update one by passing its id. This writes personal data to the merchant's Loyverse account, so only pass details the customer has given.
Inputs: name (required), id, city, note, +7 more.
Create a discount, or update one by passing its id.
Inputs: name (required), type (required), id, stores, +3 more.
Create a catalogue item, or update one by passing its id. Loyverse uses POST for both. Stock cannot be set here; create the item first, then call loyverse_set_inventory.
Inputs: item_name (required), id, form, color, +15 more.
Create a modifier group with its options, or update one by passing its id.
Inputs: name (required), id, stores, position, +1 more.
Register a till device against a store, or rename one by passing its id.
Inputs: name (required), store_id (required), id.
Create a supplier, or update one by passing its id.
Inputs: name (required), id, city, note, +9 more.
Create a tax rate, or update one by passing its id.
Inputs: name (required), rate (required), type (required), id, +1 more.
Create a variant on an existing item, or update one by passing variant_id. Use this to change a price without rewriting the whole item.
Inputs: item_id (required), sku, cost, stores, +8 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 41 tools
Each resource has its own list/get/upsert family, and actions like create_receipt, refund_receipt, and sales_summary are clearly separated. The only real ambiguity is loyverse_delete, which is a generic deletion tool with no resource in the name, plus some overlap between list_items/list_variants and get_item/get_variant.
The loyverse_ prefix and snake_case verb_noun pattern are used almost everywhere (list_*, get_*, upsert_*, create_*, set_*). It loses a point for loyverse_delete lacking a noun and loyverse_sales_summary not following the verb_noun convention.
At 41 tools this is far above the comfortable range, even for a broad retail POS domain. The count is defensible because it covers many entities, but it is heavy and likely to increase the agent's selection overhead.
The catalogue, inventory, sales/refund, reporting, customer, and loyalty workflows are well covered with list/get/upsert and lifecycle actions. Gaps remain around store/employee/payment-type management and webhook deletion, but most are either account-level or workaroundable via the generic delete tool.
Query Loyverse POS receipts, shifts, items, inventory and customers, and update stock and customers.
Connect Amazon Seller Central to Claude or ChatGPT via MCP. Orders, inventory, pricing, fees, FBA.
Connect your Odoo to Claude and ChatGPT: ask about sales, stock, customers and invoices.
Run your Tecopos business from your AI: sales, inventory, cash, customers, purchases and reports.