What can you do with this server?

This server exposes the Loyverse point-of-sale API (v1.0) as MCP tools, enabling AI assistants to query and manage retail operations data directly from chat. It works with any MCP-compatible client (Claude, Gemini CLI, opencode, etc.). Merchant & Stores * Get merchant account info; list/get stores Product Catalog * Items: Full CRUD (with nested variants) * Categories: Full CRUD * Modifiers: Full CRUD Pricing & Promotions * Discounts: Full CRUD * Taxes: Full CRUD Inventory * List stock levels per variant/store * Update stock quantities Customers & Suppliers * Customers: Full CRUD * Suppliers: Full CRUD Staff & Devices * List/get employees and POS devices Sales & Transactions * Receipts: List, get, and create (update/delete not supported by Loyverse) * Shifts: List/get cash register shift reports * Payment types: List/get Webhooks * List, create, and delete webhooks for Loyverse event notifications General: All list tools support cursor-based pagination with an optional fetch_all mode (capped at 20 pages), filtering via query parameters, and Loyverse error messages are returned verbatim for self-correction.

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcploy list my stores" 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.

mcploy

by ogarciabrena

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

mcploy

Un servidor MCP que expone la API de Loyverse (https://api.loyverse.com/v1.0) como herramientas para asistentes de IA — consulta y administra tiendas, productos, inventario, clientes, recibos, cortes de caja y más, directo desde un chat con Claude, Gemini CLI, o cualquier otro cliente compatible con MCP.

Es un wrapper delgado y genérico: un pequeño registro de recursos de Loyverse genera automáticamente las herramientas list/get/create/update/delete, en vez de código escrito a mano por endpoint. Ver Diseño para el porqué.

Requisitos

Node.js 18+
Una cuenta de Loyverse y un token de acceso personal

Related MCP server: shopify-mcp-server

Instalación

git clone https://github.com/ogarciabrena/mcploy.git
cd mcploy
npm install
npm run build

Obtener un token de acceso de Loyverse

En el Back Office de Loyverse: Configuración > Fichas de Acceso ("Access Tokens" en inglés) > crear una ficha.

Configuración

Copia .env.example a .env y pon tu token, o expórtalo directamente:

cp .env.example .env
# edita .env y define LOYVERSE_ACCESS_TOKEN

.env está en .gitignore — tu token nunca se sube al repo.

Verificar que funciona

Sin conectar ningún cliente todavía, puedes confirmar que el servidor arranca y expone las tools correctamente con el MCP Inspector:

LOYVERSE_ACCESS_TOKEN=tu-token npx @modelcontextprotocol/inspector node dist/index.js

Esto abre una UI donde puedes ver la lista completa de tools y probarlas manualmente (por ejemplo loyverse_list_store, que es de solo lectura y segura para probar primero).

Cómo usarlo

Claude Code

claude mcp add loyverse -e LOYVERSE_ACCESS_TOKEN=tu-token -- node /ruta/absoluta/a/mcploy/dist/index.js

Claude Desktop / cualquier cliente MCP con config JSON

{
  "mcpServers": {
    "loyverse": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcploy/dist/index.js"],
      "env": {
        "LOYVERSE_ACCESS_TOKEN": "tu-token"
      }
    }
  }
}

opencode

Copia opencode.jsonc.example a opencode.jsonc (raíz del proyecto o config de usuario) y pon tu token — también está en .gitignore:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "loyverse": {
      "type": "local",
      "command": ["node", "/ruta/absoluta/a/mcploy/dist/index.js"],
      "environment": {
        "LOYVERSE_ACCESS_TOKEN": "tu-token"
      }
    }
  }
}

Verifica la conexión con opencode mcp list (debe salir ✓ loyverse connected) y pregunta algo con opencode run "lista las tiendas de loyverse". Probado en vivo con google/gemini-2.5-flash — funciona igual que con Claude, sin cambiar nada del servidor. Un detalle: opencode antepone el nombre del servidor al de la tool, así que loyverse_list_store aparece como loyverse_loyverse_list_store en sus logs — no es un bug, es solo cómo opencode namespacea las tools de cada MCP server.

Otros clientes (Gemini CLI, etc.)

El servidor solo habla el protocolo MCP estándar por stdio — no tiene código específico de Claude ni de Anthropic en ningún lado. Cualquier cliente compatible con MCP puede ejecutar node dist/index.js con LOYVERSE_ACCESS_TOKEN definido y usarlo igual.

Herramientas

Para cada recurso, las herramientas que existen son exactamente las operaciones que soporta:

Recurso	list	get	create	update	delete
`merchant`		✓ (único)
`stores`	✓	✓
`categories`	✓	✓	✓	✓	✓
`items`	✓	✓	✓	✓	✓
`modifiers`	✓	✓	✓	✓	✓
`discounts`	✓	✓	✓	✓	✓
`taxes`	✓	✓	✓	✓	✓
`customers`	✓	✓	✓	✓	✓
`employees`	✓	✓
`pos_devices`	✓	✓
`suppliers`	✓	✓	✓	✓	✓
`inventory`	✓			✓ (niveles de stock)
`shifts`	✓	✓
`receipts`	✓	✓	✓
`payment_types`	✓	✓
`webhooks`	✓		✓		✓

Nombres de las tools: loyverse_<operación>_<recurso en singular>, por ejemplo loyverse_list_item, loyverse_get_store, loyverse_create_customer, loyverse_update_category, loyverse_delete_discount.

Tools de list reciben query (filtros extra, se mandan tal cual), limit, cursor, y fetch_all (sigue la paginación automáticamente, con tope de 20 páginas).
Tools de get/update/delete reciben id.
Tools de create/update reciben body, un objeto JSON libre con los campos del recurso. Update no es un parche parcial — Loyverse espera el objeto completo (ver Diseño).

Estructura del proyecto

src/
  index.ts       # arranca el servidor MCP (transporte stdio) y registra las tools
  client.ts       # cliente HTTP: auth Bearer, paginación por cursor, reintentos en 429
  resources.ts     # registro de recursos de Loyverse (fuente única de verdad)
  tools.ts         # genera las tools MCP a partir de resources.ts

Diseño

La documentación oficial (developer.loyverse.com/docs) es una aplicación JS de una sola página que no se puede scrapear de la forma usual, así que en vez de escribir a mano un schema Zod por cada campo de cada recurso (arriesgándome a inventar nombres de campo que queden fijos en el código), el servidor toma otro enfoque:

src/resources.ts es un registro pequeño: nombre del recurso, path de la API, y qué operaciones soporta.
src/tools.ts genera las tools de MCP a partir de ese registro — una función por operación, reutilizada para todos los recursos.
Los campos de body/query se mandan tal cual a la API de Loyverse como JSON. Si un campo está mal, el propio mensaje de error de Loyverse regresa textual, así quien llama (humano o LLM) se puede autocorregir en vez de chocar con un schema fijo que está mal silenciosamente.

Todos los endpoints de list del registro fueron verificados en vivo contra una cuenta real de Loyverse. Dos rutas que supuse resultaron mal y se corrigieron en el proceso: points_of_sale no existe (el endpoint real es pos_devices), y customer_groups no es un recurso real de la API pública (se probaron varias variantes de path, todas 404, se eliminó). shifts no aparece en la documentación oficial pero es un endpoint real que funciona. Las operaciones create/update/delete están menos probadas — si alguna falla, abre un issue o un PR contra src/resources.ts.

Limitaciones conocidas

receipts solo soporta list/get/create — la API de Loyverse no permite actualizar ni borrar recibos.
Los endpoints de update usan POST al path de la colección con el id dentro del body (así lo maneja Loyverse), y esperan el objeto completo, no solo el campo que cambia.
Las tools loyverse_delete_* son destructivas e irreversibles — Loyverse no tiene deshacer.
La paginación es por cursor; fetch_all tiene un tope de 20 páginas como salvaguarda contra loops descontrolados.

Contribuir

¿Encontraste un recurso con un path incorrecto, un campo que Loyverse rechaza, o un endpoint que falta? src/resources.ts es la única fuente de verdad — agrega o corrige una entrada ahí y las tools se regeneran solas. PRs e issues son bienvenidos.

Licencia

MIT

Available Tools

54 tools

loyverse_create_categoryCreate categoryB

Create a new category in Loyverse (POST /categories). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_customerCreate customerA

Create a new customer in Loyverse (POST /customers). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_discountCreate discountA

Create a new discount in Loyverse (POST /discounts). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_itemCreate itemA

Create a new item in Loyverse (POST /items). Items contain nested variants. Variant stock is managed via the inventory resource. Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_modifierCreate modifierA

Create a new modifier in Loyverse (POST /modifiers). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_receiptCreate receiptA

Create a new receipt in Loyverse (POST /receipts). Receipts cannot be updated or deleted through the API, only created and read. Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_supplierCreate supplierA

Create a new supplier in Loyverse (POST /suppliers). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_taxCreate taxB

Create a new tax in Loyverse (POST /taxes). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_create_webhookCreate webhookA

Create a new webhook in Loyverse (POST /webhooks). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: body (required).

loyverse_delete_categoryDelete categoryA

Delete a category by id (DELETE /categories/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_delete_customerDelete customerA

Delete a customer by id (DELETE /customers/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_delete_discountDelete discountA

Delete a discount by id (DELETE /discounts/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_delete_itemDelete itemA

Delete a item by id (DELETE /items/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_delete_modifierDelete modifierA

Delete a modifier by id (DELETE /modifiers/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_delete_supplierDelete supplierA

Delete a supplier by id (DELETE /suppliers/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_delete_taxDelete taxA

Delete a tax by id (DELETE /taxes/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_delete_webhookDelete webhookA

Delete a webhook by id (DELETE /webhooks/{id}). This is destructive and cannot be undone.

Inputs: id (required).

loyverse_get_categoryGet categoryA

Get a single category by id (GET /categories/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_customerGet customerA

Get a single customer by id (GET /customers/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_discountGet discountA

Get a single discount by id (GET /discounts/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_employeeGet employeeA

Get a single employee by id (GET /employees/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_itemGet itemA

Get a single item by id (GET /items/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_merchantGet merchantA

Get the Loyverse merchant (GET /merchant). Singleton resource: the merchant account itself. No id required. Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: no named parameters.

loyverse_get_modifierGet modifierA

Get a single modifier by id (GET /modifiers/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_payment_typeGet payment_typeA

Get a single payment_type by id (GET /payment_types/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_pos_deviceGet pos_deviceA

Get a single pos_device by id (GET /pos_devices/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_receiptGet receiptA

Get a single receipt by id (GET /receipts/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_shiftGet shiftA

Get a single shift by id (GET /shifts/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_storeGet storeA

Get a single store by id (GET /stores/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_supplierGet supplierA

Get a single supplier by id (GET /suppliers/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_get_taxGet taxA

Get a single tax by id (GET /taxes/{id}). Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.

Inputs: id (required).

loyverse_list_categoryList categoriesA

List categories from Loyverse (GET /categories). Supports cursor pagination. Field names follow the Loyverse API v1.0 (developer.loyverse.com/docs). If a call fails with a 400, the error message from Loyverse is returned verbatim — adjust the fields and retry.