lightspeed-x-mcp

Un servidor de Model Context Protocol para Lightspeed X (Lightspeed Retail POS, la plataforma anteriormente conocida como Vend). Ofrece a Claude, o a cualquier cliente MCP, acceso de solo lectura a las ventas, el inventario, los productos y los clientes de tu tienda, y hace la agregación por ti: ingresos, unidades, COGS, beneficio bruto, margen, descuento, valor medio de cesta y tamaño de cesta, agrupados por la dimensión que pidas.

Solo lectura por construcción. Cada herramienta emite peticiones GET. No hay ninguna ruta de código en este servidor que pueda crear, actualizar o eliminar nada en tu cuenta, así que puedes apuntarlo a un negocio minorista real sin preocuparte.

"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

Por qué existe esto

La API de Lightspeed X es una superviviente de la era Vend y tiene algunas aristas que hacen que los clientes ingenuos sean lentos o se equivoquen silenciosamente. Este servidor las maneja para que el modelo no tenga que hacerlo:

Cómo se deriva el cálculo de ingresos

Verificado contra 200 ventas reales consecutivas. Cada una conciliada con el totals.price de la propia venta con una diferencia de dos céntimos:

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.total

Tres comprobaciones adicionales sobre datos reales, todas exactas:

• La suma de los ingresos por día durante una semana equivale al total general de la semana.

• La fila de un outlet en un informe group_by: outlet equivale al mismo informe reejecutado con el filtro del lado del servidor de ese outlet.

• La suma de los importes pagados por tipo de pago equivale a los ingresos con impuestos incluidos.

Related MCP server: Toast MCP

Instalación

Opción 1: como plugin de Claude Code (recomendado)

Tres comandos, sin clonar, sin compilar, sin rutas que editar:

/plugin marketplace add genvjacobc/lightspeed-x-mcp
/plugin install lightspeed-x@lightspeed-x-mcp
/lightspeed-x:setup

El tercer comando ejecuta una skill de configuración incluida que te guía para obtener un token, lo escribe en el lugar correcto y verifica la conexión contra tu cuenta real antes de decirte que ha funcionado.

El plugin también incluye una skill reports para que Claude sepa qué herramienta responde a cada tipo de pregunta minorista y cómo leer los números que recibe.

Las credenciales viven en ${CLAUDE_PLUGIN_DATA}/credentials.env, un directorio por usuario que sobrevive a las actualizaciones del plugin. Nada se comparte entre máquinas o compañeros de equipo.

Ten en cuenta que /plugin uninstall elimina ese directorio, así que desinstalar y reinstalar significa volver a ejecutar la configuración. El token en sí permanece activo en Lightspeed de todos modos, así que revócalo allí si has terminado con él.

Opción 2: como servidor MCP independiente

git clone https://github.com/genvjacobc/lightspeed-x-mcp.git
cd lightspeed-x-mcp
npm install
npm run build

Requiere Node 18 o superior.

Obtener un token de API

En el back office de Lightspeed X: Setup → Personal Tokens → Add Personal Token. Cópialo antes de cerrar el diálogo; solo se muestra una vez.

Dos límites que conviene conocer antes de planificar un despliegue:

• Solo los usuarios administradores pueden crear tokens personales, y Lightspeed restringe la función a los planes Plus. Si Personal Tokens no aparece en Setup, alguien con acceso de administrador tiene que crear el token por ti.

• Lightspeed no ofrece tokens de solo lectura. Un token lleva todos los permisos del usuario que lo creó. Este servidor solo emite GET, pero el token en sí es una credencial de propósito general, así que trátalo como una contraseña y revócalo desde la misma pantalla si se filtra.

Comprobar que funciona

npm run doctor

Esto valida tus credenciales, llama a la API real y nombra la causa exacta de cualquier fallo. Un dominio de tienda incorrecto y un token malo devuelven ambos HTTP 401 de Lightspeed, así que el doctor informa de ambas posibilidades en lugar de adivinar.

Configurar

Copia .env.example a .env y rellena tu tienda:

LIGHTSPEED_DOMAIN=mystore
LIGHTSPEED_TOKEN=your_personal_token

LIGHTSPEED_DOMAIN acepta un prefijo simple (mystore), un host (mystore.retail.lightspeed.app) o una URL completa. Los tres resuelven al mismo lugar.

Varias tiendas. Cualquier par LIGHTSPEED_<NAME>_DOMAIN + LIGHTSPEED_<NAME>_TOKEN define una cuenta llamada <name>, en minúsculas. Las herramientas aceptan entonces un argumento opcional account:

LIGHTSPEED_NORTH_DOMAIN=northstore
LIGHTSPEED_NORTH_TOKEN=token_for_north
LIGHTSPEED_SOUTH_DOMAIN=southstore
LIGHTSPEED_SOUTH_TOKEN=token_for_south
LIGHTSPEED_DEFAULT_ACCOUNT=north

Los valores ya presentes en el entorno siempre ganan al archivo .env, así que un host que inyecta credenciales directamente tiene prioridad.

Registrar con Claude Code (solo ruta independiente)

Omite esto si instalaste el plugin; el plugin registra el servidor por sí mismo.

claude mcp add lightspeed-x -s user -- node /absolute/path/to/lightspeed-x-mcp/dist/index.js

O añádelo a tu configuración manualmente:

{
  "mcpServers": {
    "lightspeed-x": {
      "command": "node",
      "args": ["/absolute/path/to/lightspeed-x-mcp/dist/index.js"],
      "env": {
        "LIGHTSPEED_DOMAIN": "mystore",
        "LIGHTSPEED_TOKEN": "your_personal_token"
      }
    }
  }
}

Para Claude Desktop, el mismo bloque va en claude_desktop_config.json.

Verifícalo localmente con el MCP Inspector:

npm run inspect

Herramientas

lightspeed_sales_report

El plato principal. Agrega un rango de fechas y lo agrupa.

| 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_sales

Transacciones individuales, de más reciente a más antigua, con expansión opcional de líneas de detalle. Para profundizar en un recibo, auditar un total o revisar devoluciones. Filtros por outlet_id, customer_id y min_total.

lightspeed_inventory_report

Existencias disponibles unidas a los nombres de producto y outlet, con el valor de venta al público y de coste de lo que hay en el estante.

status es el argumento que importa:

group_by agrega a product, outlet, category, brand o supplier, que es como respondes a «cuánto valor de inventario hay en cada categoría».

lightspeed_search_products

Búsqueda de texto libre sobre nombre, nombre de variante, SKU y handle, con filtros de marca / proveedor / categoría / etiqueta. La coincidencia se ejecuta localmente contra el catálogo en caché porque el endpoint de búsqueda de la propia API clasifica mal, así que los resultados son coincidencias exactas de subcadena.

lightspeed_get_product

Detalle completo de un producto por ID o SKU exacto, incluido el stock por outlet y el margen calculado.

lightspeed_search_customers / lightspeed_get_customer

Busca clientes por correo electrónico (enviado a la API), o por nombre, teléfono o código de cliente (coincidencia local). Devuelve el UUID que las herramientas de ventas aceptan como filtro customer_id. Esto devuelve datos personales; trátalos en consecuencia.

lightspeed_list_outlets / lightspeed_list_registers / lightspeed_list_accounts

Resuelve nombres de tienda a los UUID de outlet que aceptan los filtros de informe, lista las líneas de TPV incluidos los registros de comercio electrónico, y ve a qué cuentas puede llegar el servidor. lightspeed_list_accounts nunca devuelve tokens.

lightspeed_list_reference_data

Una herramienta sobre brands, suppliers, product_categories, tags, customer_groups, payment_types, promotions, taxes y users. Úsala para obtener la ortografía exacta de una marca o categoría antes de filtrar un informe por ella.

lightspeed_api_get

Vía de escape para cualquier endpoint sin una herramienta específica: /consignments, /price_books, /serial_numbers, etc. Solo se emiten peticiones GET.

Rendimiento y límites

Los informes están condicionados por el hecho de que las ventas no se pueden filtrar por fecha en el servidor.

La mayor parte de una llamada en frío son las ~30 sondas de una sola fila que localizan el rango de fechas. Esas sondas se recuerdan por cuenta, así que el segundo informe de una sesión normalmente no necesita ninguna. Los escaneos de catálogo, establecimiento, caja, usuario e inventario se almacenan en caché durante 15 minutos.

Para mantener la rapidez: pasa outlet_id cuando solo te interese una tienda, y prefiere rangos de fechas estrechos. LIGHTSPEED_MAX_SALES (por defecto 200.000) limita una sola llamada, y la herramienta te indica claramente cuando trunca en lugar de devolver silenciosamente una respuesta parcial.

Una advertencia honesta. Como el rango de fechas se localiza por versión, una venta creada antes del rango pero editada después puede pasarse por alto. LIGHTSPEED_SEEK_MARGIN_DAYS (por defecto 1) establece cuánto antes del rango apunta la búsqueda, y aumentarlo amplía la red de seguridad a costa de escanear más registros. Esto es inherente a una API que no filtra por fecha, no un atajo tomado aquí.

Referencia de configuración

Desarrollo

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 manifests

src/
  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 group

Las herramientas devuelven tablas Markdown en lugar de JSON sin procesar: un modelo lee una tabla alineada de forma más fiable que un blob JSON profundo, con una fracción de los tokens. Los números subyacentes también están en structuredContent para quienes llaman programáticamente.

Dos convenciones que vale la pena mantener si contribuyes:

• Nunca lances una excepción desde un manejador de herramienta. Los fallos se devuelven como resultados isError. El envoltorio guard() lo garantiza.

• Nunca uses console.log. La salida estándar transporta tramas JSON-RPC. Los diagnósticos van a console.error.

Estructura del repositorio

.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
src/                TypeScript source
dist/               compiled output, committed so plugin installs need no build

dist/ se rastrea intencionadamente en git, porque la instalación del plugin de Claude Code no ejecuta un paso de compilación y el servidor compilado debe viajar con el repositorio. Ejecuta npm run build antes de confirmar un cambio de código fuente, y sube la version en package.json, .claude-plugin/plugin.json y .claude-plugin/marketplace.json a la vez al publicar.

Licencia

MIT. Consulta LICENSE.

No está afiliado ni respaldado por Lightspeed Commerce.