nagoc-loyverse-mcp

A Model Context Protocol (MCP) server for the Loyverse POS REST API.
Connect Claude Desktop (or any MCP-compatible AI client) to your Loyverse account to query and manage your retail data through natural language.

Features

• Full API coverage — all 16 Loyverse resources: Categories, Customers, Discounts, Employees, Inventory, Items, Modifiers, Payment Types, POS Devices, Receipts, Shifts, Stores, Suppliers, Taxes, Variants, and Merchant info
• Human-in-the-loop — every write or destructive tool (POST / DELETE) first shows a preview of what will happen and requires an explicit confirm: true before executing — your data is never modified by accident
• No credential storage — your API token is passed only as an environment variable; the MCP server never stores, logs, or exposes it
• Pagination support — all list endpoints expose limit and cursor parameters
• Soft-delete aware — resources that support soft-deletion expose a show_deleted filter

Prerequisites

You need three things before you can use this MCP server. Follow the steps below to get each one.

1. Node.js (version 18 or higher)

Node.js is the runtime that powers this server. If you're not sure whether you have it:

1. Open your terminal (Command Prompt / PowerShell on Windows, Terminal on Mac)
2. Type node -v and press Enter
3. If you see a version number like v18.x.x or higher, you're good to go
4. If you get an error or the version is lower than 18, download the latest LTS version from nodejs.org and run the installer

npm (the package manager) is included automatically when you install Node.js — no separate install needed.

2. Claude Desktop

This is the AI app you'll chat with. It uses the MCP server to talk to your Loyverse account.

• Download it from claude.ai/download
• Install and sign in with your Anthropic account

3. Your Loyverse API Token

This is the key that allows the MCP server to access your Loyverse data. It stays on your machine and is never shared.

How to get it:

1. Log into your Loyverse Back Office
2. Go to Settings → Integrations → Personal Access Tokens
3. Click Generate new token
4. Give it a name (e.g. Claude MCP) and click Generate
5. Copy the token immediately — you won't be able to see it again after closing the page

⚠️ Treat this token like a password. Anyone who has it can read and modify your Loyverse account data.

Installation

Option A — Use directly with npx (recommended)

No installation needed. Claude Desktop runs the server on demand and always pulls the latest published version automatically — users never need to reinstall when you publish an update.

// claude_desktop_config.json
{
  "mcpServers": {
    "loyverse": {
      "command": "npx",
      "args": ["-y", "nagoc-loyverse-mcp@latest"],
      "env": {
        "LOYVERSE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Option B — Install globally

npm install -g nagoc-loyverse-mcp

Then configure Claude Desktop:

{
  "mcpServers": {
    "loyverse": {
      "command": "nagoc-loyverse-mcp",
      "env": {
        "LOYVERSE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Desktop Configuration

The config file is located at:

| OS | Path | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

After editing, restart Claude Desktop. You should see the Loyverse tools available in the tool selector.

Environment Variables

| Variable | Required | Description | |---|---|---| | LOYVERSE_API_TOKEN | ✅ Yes | Your Loyverse personal access token (Bearer token) |

Tools Reference

All tool names are prefixed with loyverse_.

Human-in-the-loop (write tools)

Every tool that creates, updates, or deletes data includes a confirm parameter:

• confirm: false (default) → Returns a preview of what will be sent to the API. Nothing is changed.
• confirm: true → Executes the action against the Loyverse API.

This two-step pattern ensures Claude always shows you what it intends to do before making any changes.

Merchant

| Tool | Description | |---|---| | loyverse_get_merchant | Get account/merchant information |

Categories

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_categories | List categories with pagination | | | loyverse_get_category | Get a single category by UUID | | | loyverse_create_update_category | Create or update a category | ✅ | | loyverse_delete_category | Delete a category | ✅ |

Customers

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_customers | List customers — filter by email, date ranges | | | loyverse_get_customer | Get a single customer by ID | | | loyverse_create_update_customer | Create or update a customer | ✅ | | loyverse_delete_customer | Delete a customer (hard delete) | ✅ |

Discounts

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_discounts | List discounts | | | loyverse_get_discount | Get a single discount | | | loyverse_create_update_discount | Create or update a discount | ✅ | | loyverse_delete_discount | Delete a discount | ✅ |

Employees (read-only)

| Tool | Description | |---|---| | loyverse_list_employees | List employees | | loyverse_get_employee | Get a single employee |

Create/update/delete employees must be done in the Loyverse Back Office.

Inventory

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_inventory | Get stock levels — filter by store and variant | | | loyverse_update_inventory | Batch update stock levels (absolute counts) | ✅ |

Items

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_items | List items (products) with variants | | | loyverse_get_item | Get a single item with all variants | | | loyverse_create_update_item | Create or update an item and its variants | ✅ | | loyverse_delete_item | Soft-delete an item | ✅ |

Modifiers

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_modifiers | List modifiers (add-ons) | | | loyverse_get_modifier | Get a single modifier | | | loyverse_create_update_modifier | Create or update a modifier | ✅ | | loyverse_delete_modifier | Delete a modifier | ✅ |

Payment Types (read-only)

| Tool | Description | |---|---| | loyverse_list_payment_types | List payment types | | loyverse_get_payment_type | Get a single payment type |

POS Devices

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_pos_devices | List POS devices | | | loyverse_get_pos_device | Get a single POS device | | | loyverse_create_update_pos_device | Create or update a POS device | ✅ | | loyverse_delete_pos_device | Delete a POS device | ✅ |

Receipts

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_receipts | List receipts — filter by store, date, order | | | loyverse_get_receipt | Get a single receipt with full details | | | loyverse_create_receipt | Create a new sales receipt | ✅ | | loyverse_create_refund | Create a refund for an existing receipt | ✅ |

Shifts (read-only)

| Tool | Description | |---|---| | loyverse_list_shifts | List cash register shifts | | loyverse_get_shift | Get a single shift with cash movement details |

Stores (read-only)

| Tool | Description | |---|---| | loyverse_list_stores | List stores | | loyverse_get_store | Get a single store |

Suppliers

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_suppliers | List suppliers | | | loyverse_get_supplier | Get a single supplier | | | loyverse_create_update_supplier | Create or update a supplier | ✅ | | loyverse_delete_supplier | Delete a supplier | ✅ |

Taxes

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_taxes | List taxes | | | loyverse_get_tax | Get a single tax | | | loyverse_create_update_tax | Create or update a tax | ✅ | | loyverse_delete_tax | Delete a tax | ✅ |

Variants

| Tool | Description | Confirm required | |---|---|---| | loyverse_list_variants | List item variants — filter by SKU, item | | | loyverse_get_variant | Get a single variant | | | loyverse_create_update_variant | Create or update a variant | ✅ | | loyverse_delete_variant | Delete a variant | ✅ |

Usage Examples

Once connected to Claude Desktop, just talk naturally:

Show me all items in my store

What's the current stock level for variant abc-123 in store xyz-456?

Create a new category called "Beverages" in blue

Claude will show you a preview first. Reply "yes, confirm" to execute.

List all receipts from last week for store ID abc-123

Refund 2 units of line item 999 from receipt R-00042

API Rate Limits

Loyverse enforces 300 requests per 300 seconds per account. The server returns the raw 429 Too Many Requests error — implement retry logic in your workflow if needed.

Security Notes

• The LOYVERSE_API_TOKEN is read from the environment at runtime and never stored, logged, or transmitted beyond Loyverse's own API
• All HTTPS communication is handled by Node's built-in fetch
• A personal access token grants full access to the target Loyverse account — treat it like a password

License

MIT