Checkbox ПРРО MCP (unofficial)

checkbox-mcp

Un servidor MCP para la API de Checkbox, un software de caja registradora ucraniano (ПРРО). Permite que un asistente de IA como Claude responda preguntas sobre recibos, turnos, informes X/Z, productos y pedidos de tu organización y, solo si lo permites explícitamente, abrir y cerrar turnos y crear recibos fiscales.

Ucraniano: README.uk.md

No oficial. Este proyecto no está afiliado ni respaldado por Checkbox. "Checkbox" es una marca comercial de su propietario. Úsalo bajo tu propio riesgo: los recibos creados mediante las herramientas de escritura son documentos fiscales reales.

Estado: 0.1.0, aún no verificado en una caja registradora real. El servidor se construye a partir del documento OpenAPI oficial (versión 2.108.3) y la wiki pública de Checkbox. Todas las pruebas se ejecutan contra una capa HTTP simulada y verifican cada solicitud contra una instantánea de ese documento OpenAPI. Nadie lo ha ejecutado aún contra la API real de Checkbox, ni con un cajero de prueba ni con uno de producción. Consulta Limitaciones.

¿Qué es un ПРРО y qué es Checkbox?

En Ucrania, la mayoría de las empresas que venden a consumidores deben registrar cada venta ante el Servicio Estatal de Impuestos (ДПС). El dispositivo o programa que hace esto es un "registrador de operaciones de liquidación" (РРО). Un ПРРО es la variante de software: en lugar de una caja registradora de hardware certificada, un programa firma cada recibo con la firma electrónica del cajero, lo envía al servicio de impuestos y recibe un número fiscal a cambio. El trabajo se organiza en turnos (зміна): un cajero abre un turno, emite recibos y cierra el turno con un informe Z, el resumen diario que se envía al servicio de impuestos. Checkbox es uno de esos servicios ПРРО; ofrece aplicaciones web y móviles y una API REST, que es con la que habla este servidor.

Inicio rápido

Necesitas Node.js 20 o superior y las credenciales de un cajero de Checkbox. Para probar el servidor, usa el cajero de prueba y la caja registradora de prueba que Checkbox crea para cada cuenta (consulta Probarlo con datos de prueba de Checkbox).

Aún no en npm. Hasta que se publique la primera versión, los comandos npx -y @myradostudio/checkbox-mcp a continuación no funcionarán. Ejecuta el servidor desde el código fuente en su lugar: git clone https://github.com/myradostudio/checkbox-mcp, luego npm install y npm run build en esa carpeta, y usa "command": "node" con "args": ["/absolute/path/to/checkbox-mcp/dist/index.js"] en las configuraciones a continuación.

Claude Desktop

Agrega el servidor a claude_desktop_config.json (Configuración → Desarrollador → Editar configuración):

{
  "mcpServers": {
    "checkbox": {
      "command": "npx",
      "args": ["-y", "@myradostudio/checkbox-mcp"],
      "env": {
        "CHECKBOX_PIN_CODE": "your cashier PIN code",
        "CHECKBOX_LICENSE_KEY": "your cash register license key"
      }
    }
  }
}

Si el servidor no se inicia en Windows, usa "command": "cmd" y "args": ["/c", "npx", "-y", "@myradostudio/checkbox-mcp"].

Claude Code

claude mcp add --transport stdio \
  --env CHECKBOX_PIN_CODE=your-pin-code \
  --env CHECKBOX_LICENSE_KEY=your-license-key \
  checkbox -- npx -y @myradostudio/checkbox-mcp

Cursor

Agrega el mismo bloque a ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json (un proyecto):

{
  "mcpServers": {
    "checkbox": {
      "command": "npx",
      "args": ["-y", "@myradostudio/checkbox-mcp"],
      "env": {
        "CHECKBOX_PIN_CODE": "your cashier PIN code",
        "CHECKBOX_LICENSE_KEY": "your cash register license key"
      }
    }
  }
}

Cualquier otro cliente MCP que pueda iniciar un servidor stdio local funciona de la misma manera: ejecuta npx -y @myradostudio/checkbox-mcp con las variables de entorno a continuación.

Luego pregunta, por ejemplo:

• "¿Con qué cajero has iniciado sesión y hay un turno abierto?"
• "Muestra los recibos de ayer y el total por forma de pago."
• "Encuentra los informes Z de la semana pasada e imprime el más reciente."
• "¿Está la caja registradora en línea? ¿Cuántos códigos sin conexión quedan?"

Configuración

El servidor se configura solo con variables de entorno. Las valida al inicio y sale con una explicación en stderr si falta algo.

Variable	Obligatoria	Predeterminado	Propósito
CHECKBOX_PIN_CODE	un método de inicio de sesión		Código PIN del cajero. El método de inicio de sesión que recomienda Checkbox. Necesita CHECKBOX_LICENSE_KEY.
CHECKBOX_LOGIN	un método de inicio de sesión		Inicio de sesión del cajero. Se usa con CHECKBOX_PASSWORD cuando no se establece un código PIN.
CHECKBOX_PASSWORD	con el inicio de sesión		Contraseña del cajero.
CHECKBOX_LICENSE_KEY	ver propósito		Clave de licencia de la caja registradora. Obligatoria para el inicio de sesión con PIN, para el modo de escritura y para las herramientas que informan sobre "esta" caja registradora (get_cash_register sin un id, get_offline_status, get_periodical_report, list_shifts con alcance cash_register).
CHECKBOX_API_URL	no	https://api.checkbox.ua	Origen de la API. Debe ser https:// (se acepta http:// simple solo para localhost).
CHECKBOX_ALLOW_WRITE	no	desactivado	Establécelo en 1 para registrar las herramientas de escritura. Cualquier otro valor que no sea 1/true/yes/on o 0/false/no/off detiene el servidor.

El código PIN y la clave de licencia se muestran en el gabinete personal de Checkbox, en las secciones de cajero y caja registradora. Si se establecen tanto un código PIN como un par de inicio de sesión/contraseña, se usa el código PIN.

Herramientas

Los montos de dinero son enteros en kopecks (13550 significa 135.50 UAH) y las cantidades son enteros en milésimas (1000 significa 1 pieza, 2250 significa 2.25 kg), exactamente como en la API de Checkbox. El servidor se lo indica al modelo.

Herramientas de lectura (siempre disponibles)

Herramienta	Qué devuelve	Llamada a la API
get_cashier_profile	El cajero con sesión iniciada, permisos, indicador de prueba y la organización	GET /api/v1/cashier/me
list_cash_registers	Cajas registradoras con número fiscal, dirección, modo en línea/sin conexión, turno abierto	GET /api/v1/cash-registers
get_cash_register	Una caja registradora por id, o la que pertenece a la clave de licencia	GET /api/v1/cash-registers/{id} o GET /api/v1/cash-registers/info
get_offline_status	Códigos fiscales sin conexión disponibles y tiempo sin conexión	GET /api/v1/cash-registers/get-offline-codes-count y …/get-offline-time
get_current_shift	El turno abierto del cajero con su saldo en curso	GET /api/v1/cashier/shift
list_shifts	Turnos del cajero, o de la caja registradora	GET /api/v1/shifts o GET /api/v1/cash-registers/shifts
get_shift	Un turno completo, incluido su informe Z una vez cerrado	GET /api/v1/shifts/{id}
search_receipts	Recibos por período, número fiscal, código de barras, turno, caja registradora, sucursal	GET /api/v1/receipts/search
get_receipt	Un recibo como JSON, o como texto imprimible	GET /api/v1/receipts/{id} o …/{id}/text
list_reports	Informes X y Z con totales por forma de pago	GET /api/v1/reports/search
get_report	Un informe como JSON, o como texto imprimible	GET /api/v1/reports/{id} o …/{id}/text
get_periodical_report	El informe periódico para un rango de fechas, como texto	GET /api/v1/reports/periodical
search_goods	Productos del catálogo de Checkbox con precios y tasas impositivas	GET /api/v1/goods
list_taxes	Tasas impositivas configuradas para la organización	GET /api/v1/cashier/tax
list_orders	Pedidos (recibos preliminares colocados por un sistema externo)	GET /api/v1/orders
get_order	Un pedido completo, incluidos los detalles de entrega del cliente	GET /api/v1/orders/{id}

Las herramientas de lista devuelven resúmenes compactos y un bloque pagination. El tamaño de página predeterminado es 25 y está limitado a 100 (50 para turnos de caja registradora, el límite de ese endpoint); next_offset le indica al modelo cómo continuar.

Herramientas de escritura (solo con CHECKBOX_ALLOW_WRITE=1)

Herramienta	Qué hace	Llamada a la API
open_shift	Abre un turno en la caja registradora de la clave de licencia	POST /api/v1/shifts
close_shift	Cierra el turno actual y crea su informe Z	POST /api/v1/shifts/close
create_sale_receipt	Crea y fiscaliza un recibo de venta	POST /api/v1/receipts/sell
create_return_receipt	Crea y fiscaliza un recibo de devolución	POST /api/v1/receipts/sell con is_return en cada línea
create_service_receipt	Introduce efectivo en la caja o lo retira	POST /api/v1/receipts/service
send_receipt_email	Envía por correo electrónico una copia de un recibo	POST /api/v1/receipts/{id}/email
send_receipt_sms	Envía una copia de un recibo por SMS/Viber (un servicio de Checkbox facturado por separado)	POST /api/v1/receipts/{id}/sms

Un recibo es un documento fiscal. Una vez creado, no se puede editar ni eliminar; un error solo se puede compensar con un recibo de devolución separado. Lo mismo ocurre con un turno abierto o cerrado.

Modelo de seguridad

Los recibos fiscales son documentos legales, por lo que el servidor es conservador por diseño.

• Solo lectura a menos que optes por más. Sin CHECKBOX_ALLOW_WRITE=1, las herramientas de escritura no se registran en absoluto: el modelo no puede verlas ni llamarlas. Cada herramienta de lectura emite solo solicitudes GET, y una prueba lo garantiza.
• Anotaciones honestas. Las herramientas de lectura llevan readOnlyHint: true. Las herramientas que crean estado fiscal (open_shift, close_shift, las tres herramientas de recibos) llevan destructiveHint: true: estrictamente hablando, agregan datos, pero el resultado no se puede deshacer, y la pista es lo que hace que los clientes MCP te pidan confirmación. Ninguna herramienta de escritura afirma ser idempotente. Si la confirmación se muestra y cómo depende de tu cliente MCP; mantén activada la aprobación por llamada para las herramientas de escritura.
• Entrada estricta. Cada herramienta rechaza argumentos que no conoce, por lo que un filtro que la API no tiene nunca se ignora silenciosamente y un discount mal escrito no puede producir un recibo con el total incorrecto. Las herramientas de escritura también rechazan montos no enteros y contactos mal formados antes de enviar cualquier cosa.
• Sin reintentos ciegos. El servidor nunca repite una escritura por sí solo, excepto una vez después de un HTTP 401, donde la solicitud fue rechazada por autenticación y se necesita un token nuevo. Si una escritura termina sin una respuesta definitiva (un tiempo de espera, una conexión rota, un error de puerta de enlace, HTTP 429, una respuesta ilegible), la herramienta dice que el resultado es desconocido y cómo verificarlo. Cada recibo nuevo recibe un UUID de antemano; Checkbox documenta que rechaza un recibo cuyo id ya existe, por lo que un reintento con ese id no puede crear un duplicado.
• Sin omitir las verificaciones propias de Checkbox. close_shift no expone la opción que omite la verificación de que un turno es cerrado por el programa que lo abrió.
• Las credenciales permanecen locales. Se leen de variables de entorno, se usan solo para solicitudes a CHECKBOX_API_URL y nunca se escriben en stdout, stderr ni en resultados de herramientas. No se siguen redirecciones, por lo que ni la clave de licencia ni un cuerpo de solicitud pueden terminar en otro host. El token de acceso vive en memoria y se revoca cuando el cliente MCP se desconecta (mejor esfuerzo: un proceso eliminado no puede hacer eso).
• Menos datos para el modelo. Las herramientas de lista devuelven resúmenes sin contactos de clientes; el número de impuestos personal del cajero se elimina de cada resultado. get_receipt y get_order sí devuelven registros completos, que pueden contener direcciones de correo electrónico, números de teléfono y direcciones de entrega de clientes.
• Sin telemetría, sin registro de datos comerciales. stderr recibe solo mensajes de inicio (problemas de configuración y un banner de una línea con el modo) y el tipo de un error de transporte. Las solicitudes y respuestas nunca se registran.

Dos cosas que el servidor no puede hacer por ti. Primero, lo que devuelve una herramienta se envía al modelo de IA que uses y a su proveedor; decide si eso es aceptable para tus datos. Segundo, los nombres de productos, comentarios y otro texto almacenado en Checkbox llegan al modelo tal cual y podrían contener instrucciones escritas por otra persona (inyección de prompts). Esa es una razón más para aprobar cada llamada de escritura tú mismo.

Probarlo con datos de prueba de Checkbox

Esto es lo que documenta Checkbox; este proyecto no se ha ejecutado aún contra ello.

• No hay un host de sandbox separado. Según la wiki, https://api.checkbox.ua es la única dirección tanto para pruebas como para trabajo fiscal. Lo que hace que una sesión sea de prueba es el cajero y la caja registradora con los que inicias sesión.
• Un cajero de prueba y una caja registradora de prueba aparecen en el gabinete personal de Checkbox automáticamente después del registro (wiki: datos de prueba). Los recibos de prueba no se envían al servicio de impuestos y se marcan como recibos de prueba. Checkbox los limita a 100 por mes.
• Para el cajero de prueba, la contraseña es la misma que el inicio de sesión (wiki: autorización).
• Checkbox advierte que nunca uses un cajero o caja registradora de producción para pruebas: los datos incorrectos enviados al servicio de impuestos deben explicarse y pueden dar lugar a una multa.

Una primera sesión razonable: configura el servidor con el cajero de prueba, deja CHECKBOX_ALLOW_WRITE sin establecer y llama a get_cashier_profile. Debería mostrar is_test: true. Solo entonces considera el modo de escritura, con las credenciales de prueba.

Limitaciones

• No verificado contra la API en vivo. Las solicitudes se verifican contra el documento OpenAPI, que describe formas, no comportamiento. El manejo de respuestas, los textos de error y el flujo de estado asíncrono se implementan a partir de la documentación.
• Un cajero por instancia del servidor, y una caja registradora para las herramientas que necesitan la clave de licencia.
• No cubierto: operaciones en modo offline (ir a offline/online, recibos offline), creación de informes X, recibos de prepago y pospago, cambio de divisas, facturas y terminales de adquisición, edición de bienes, cartas de porte de servicios de entrega (ЕТТН), webhooks, informes extendidos, plantillas de recibos.
• search_receipts no puede filtrar por estado o tipo, porque la API no tiene tal parámetro; la herramienta devuelve ambos campos para cada recibo. Por defecto, la API devuelve solo los recibos creados por el cajero que ha iniciado sesión.
• La fiscalización es asíncrona. Un nuevo recibo o turno regresa en estado CREATED; el modelo debe consultar get_receipt o get_current_shift. El servidor no espera.
• En un recibo de devolución, los pagos se envían como montos positivos. El documento OpenAPI no lo especifica; debe confirmarse en una caja registradora de prueba.
• Sin totales para la mayoría de las listas. La API informa un total solo para pedidos, por lo que el servidor solo puede decir que puede haber una página siguiente.
• Los límites de velocidad no se aplican en el servidor. Checkbox documenta un límite de dos recibos nuevos por segundo por caja registradora (excederlo bloquea la caja durante 5 segundos) y bloquea vistas repetidas del mismo recibo a tres solicitudes por segundo.
• Tokens. Checkbox documenta como máximo tres tokens válidos por cajero. El servidor inicia sesión una vez al inicio, vuelve a iniciar sesión después de un HTTP 401 solo si su token tiene más de un minuto, y cierra sesión al desconectarse; incluso así, un cajero que también haya iniciado sesión en otro lugar puede verse afectado.
• No mezcle programas dentro de un turno. Checkbox advierte que un turno abierto a través de la API no debe operarse desde las aplicaciones Checkbox Kasa o Manager al mismo tiempo.
• Tiempo de espera fijo de 30 segundos por solicitud.

Desarrollo

npm install
npm run lint          # tsc --noEmit over src/ and tests/
npm test              # builds dist/ and the tests, then runs them with node:test
npm run spec:update   # refreshes the OpenAPI snapshot from api.checkbox.ua

• src/endpoints.ts es el catálogo de operaciones de API que el servidor llama. tests/spec.test.ts lo compara con spec/checkbox-api.snapshot.json, una copia reducida del documento OpenAPI oficial (solo parámetros, esquemas de solicitud y seguridad de esas operaciones).
• Cada prueba de herramienta llama a la herramienta a través de un cliente MCP real y pasa cada solicitud registrada a través de assertMatchesSpec, que verifica la ruta, los parámetros de consulta, los encabezados y el cuerpo contra esa instantánea.
• tests/e2e.test.ts inicia el servidor compilado como un proceso hijo sobre stdio contra un mock HTTP local.
• Para probar el servidor manualmente: npx @modelcontextprotocol/inspector node dist/index.js.

El servidor utiliza el SDK oficial de TypeScript (@modelcontextprotocol/server) y zod; no hay otras dependencias de tiempo de ejecución.

Se aceptan problemas y solicitudes de extracción. Para informes de seguridad, consulte SECURITY.md.

Creado por

Creado y mantenido por Myrado Studio — servidores MCP personalizados, agentes de IA y automatización. ¿Necesita un servidor MCP para su propio sistema? https://myradostudio.com/en/mcp-server-development/

Licencia

MIT © 2026 Myrado Studio