Checkbox ПРРО MCP (unofficial)

checkbox-mcp

Um servidor MCP para a API do Checkbox, um registro eletrônico de caixa ucraniano (ПРРО). Ele permite que um assistente de IA, como o Claude, responda perguntas sobre recibos, turnos, relatórios X/Z, mercadorias e pedidos da sua organização e, somente se você permitir explicitamente, abra e feche turnos e crie recibos fiscais.

Українською: README.uk.md

Não oficial. Este projeto não é afiliado ou endossado pela Checkbox. "Checkbox" é uma marca registrada do seu proprietário. Use por sua conta e risco: recibos criados por meio das ferramentas de escrita são documentos fiscais reais.

Status: 0.1.0, ainda não verificado em um caixa registradora real. O servidor é construído a partir do documento OpenAPI oficial (versão 2.108.3) e do wiki público do Checkbox. Todos os testes são executados contra uma camada HTTP simulada e verificam cada solicitação em relação a um snapshot desse documento OpenAPI. Ninguém o executou contra a API real do Checkbox ainda, nem com um caixa de teste nem com um de produção. Consulte Limitações.

O que é um ПРРО e o que é o Checkbox?

Na Ucrânia, a maioria das empresas que vendem para consumidores precisa registrar cada venda no Serviço Fiscal do Estado (ДПС). O dispositivo ou programa que faz isso é um "registrador de operações de liquidação" (РРО). Um ПРРО é a variante de software: em vez de uma caixa registradora de hardware certificada, um programa assina cada recibo com a assinatura eletrônica do caixa, envia-o ao serviço fiscal e recebe um número fiscal de volta. O trabalho é organizado em turnos (зміна): um caixa abre um turno, emite recibos e fecha o turno com um relatório Z, o resumo diário que vai para o serviço fiscal. Checkbox é um desses serviços ПРРО; ele oferece aplicativos web e móveis e uma API REST, que é com a qual este servidor se comunica.

Início rápido

Você precisa do Node.js 20 ou mais recente e das credenciais de um caixa do Checkbox. Para testar o servidor, use o caixa de teste e a caixa registradora de teste que o Checkbox cria para cada conta (consulte Testando com dados de teste do Checkbox).

Ainda não está no npm. Até que a primeira versão seja publicada, os comandos npx -y @myradostudio/checkbox-mcp abaixo não funcionarão. Execute o servidor a partir do código-fonte: git clone https://github.com/myradostudio/checkbox-mcp, depois npm install e npm run build nessa pasta, e use "command": "node" com "args": ["/absolute/path/to/checkbox-mcp/dist/index.js"] nas configurações abaixo.

Claude Desktop

Adicione o servidor a claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config):

{
  "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"
      }
    }
  }
}

Se o servidor não iniciar no Windows, use "command": "cmd" e "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

Adicione o mesmo bloco a ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto):

{
  "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"
      }
    }
  }
}

Qualquer outro cliente MCP que possa iniciar um servidor stdio local funciona da mesma forma: execute npx -y @myradostudio/checkbox-mcp com as variáveis de ambiente abaixo.

Em seguida, pergunte, por exemplo:

• "Em qual caixa você está conectado e há um turno aberto?"
• "Mostre os recibos de ontem e o total por forma de pagamento."
• "Encontre os relatórios Z da semana passada e imprima o mais recente."
• "A caixa registradora está online? Quantos códigos offline restam?"

Configuração

O servidor é configurado apenas com variáveis de ambiente. Ele as valida na inicialização e sai com uma explicação no stderr se algo estiver faltando.

Variável	Obrigatório	Padrão	Finalidade
CHECKBOX_PIN_CODE	um método de login		Código PIN do caixa. O método de login recomendado pelo Checkbox. Precisa de CHECKBOX_LICENSE_KEY.
CHECKBOX_LOGIN	um método de login		Login do caixa. Usado com CHECKBOX_PASSWORD quando nenhum código PIN está definido.
CHECKBOX_PASSWORD	com o login		Senha do caixa.
CHECKBOX_LICENSE_KEY	consulte a finalidade		Chave de licença da caixa registradora. Necessária para login com PIN, para o modo de escrita e para as ferramentas que relatam sobre "esta" caixa registradora (get_cash_register sem um id, get_offline_status, get_periodical_report, list_shifts com escopo cash_register).
CHECKBOX_API_URL	não	https://api.checkbox.ua	Origem da API. Deve ser https:// (http:// simples é aceito apenas para localhost).
CHECKBOX_ALLOW_WRITE	não	desligado	Defina como 1 para registrar as ferramentas de escrita. Qualquer outro valor diferente de 1/true/yes/on ou 0/false/no/off interrompe o servidor.

O código PIN e a chave de licença são mostrados no painel pessoal do Checkbox, nas seções de caixa e caixa registradora. Se tanto um código PIN quanto um par de login/senha estiverem definidos, o código PIN será usado.

Ferramentas

Os valores monetários são números inteiros em copeques (13550 significa 135,50 UAH) e as quantidades são números inteiros em milésimos (1000 significa 1 peça, 2250 significa 2,25 kg), exatamente como na API do Checkbox. O servidor informa isso ao modelo.

Ferramentas de leitura (sempre disponíveis)

Ferramenta	O que retorna	Chamada de API
get_cashier_profile	O caixa conectado, permissões, sinalizador de teste e a organização	GET /api/v1/cashier/me
list_cash_registers	Caixas registradoras com número fiscal, endereço, modo online/offline, turno aberto	GET /api/v1/cash-registers
get_cash_register	Uma caixa registradora por id, ou aquela à qual a chave de licença pertence	GET /api/v1/cash-registers/{id} ou GET /api/v1/cash-registers/info
get_offline_status	Códigos fiscais offline disponíveis e tempo gasto offline	GET /api/v1/cash-registers/get-offline-codes-count e …/get-offline-time
get_current_shift	O turno aberto do caixa com seu saldo atual	GET /api/v1/cashier/shift
list_shifts	Turnos do caixa, ou da caixa registradora	GET /api/v1/shifts ou GET /api/v1/cash-registers/shifts
get_shift	Um turno completo, incluindo seu relatório Z após o fechamento	GET /api/v1/shifts/{id}
search_receipts	Recibos por período, número fiscal, código de barras, turno, caixa registradora, filial	GET /api/v1/receipts/search
get_receipt	Um recibo como JSON, ou como texto imprimível	GET /api/v1/receipts/{id} ou …/{id}/text
list_reports	Relatórios X e Z com totais por forma de pagamento	GET /api/v1/reports/search
get_report	Um relatório como JSON, ou como texto imprimível	GET /api/v1/reports/{id} ou …/{id}/text
get_periodical_report	O relatório periódico para um intervalo de datas, como texto	GET /api/v1/reports/periodical
search_goods	Mercadorias do catálogo do Checkbox com preços e alíquotas de impostos	GET /api/v1/goods
list_taxes	Alíquotas de impostos configuradas para a organização	GET /api/v1/cashier/tax
list_orders	Pedidos (recibos de rascunho colocados por um sistema externo)	GET /api/v1/orders
get_order	Um pedido completo, incluindo detalhes de entrega do cliente	GET /api/v1/orders/{id}

As ferramentas de lista retornam resumos compactos e um bloco pagination. O tamanho da página padrão é 25 e o máximo é 100 (50 para turnos de caixa registradora, o limite desse endpoint); next_offset informa ao modelo como continuar.

Ferramentas de escrita (somente com CHECKBOX_ALLOW_WRITE=1)

Ferramenta	O que faz	Chamada de API
open_shift	Abre um turno na caixa registradora da chave de licença	POST /api/v1/shifts
close_shift	Fecha o turno atual e cria seu relatório Z	POST /api/v1/shifts/close
create_sale_receipt	Cria e fiscaliza um recibo de venda	POST /api/v1/receipts/sell
create_return_receipt	Cria e fiscaliza um recibo de devolução	POST /api/v1/receipts/sell com is_return em cada linha
create_service_receipt	Coloca dinheiro na caixa registradora ou o retira	POST /api/v1/receipts/service
send_receipt_email	Envia por e-mail uma cópia de um recibo	POST /api/v1/receipts/{id}/email
send_receipt_sms	Envia uma cópia de um recibo por SMS/Viber (um serviço do Checkbox cobrado separadamente)	POST /api/v1/receipts/{id}/sms

Um recibo é um documento fiscal. Depois de criado, não pode ser editado ou excluído; um erro só pode ser compensado com um recibo de devolução separado. O mesmo vale para um turno aberto ou fechado.

Modelo de segurança

Recibos fiscais são documentos legais, portanto o servidor é conservador por design.

• Somente leitura, a menos que você opte por participar. Sem CHECKBOX_ALLOW_WRITE=1, as ferramentas de escrita não são registradas: o modelo não pode vê-las ou chamá-las. Cada ferramenta de leitura emite apenas solicitações GET, e um teste garante isso.
• Anotações honestas. As ferramentas de leitura carregam readOnlyHint: true. As ferramentas que criam estado fiscal (open_shift, close_shift, as três ferramentas de recibo) carregam destructiveHint: true: estritamente falando, elas adicionam dados, mas o resultado não pode ser desfeito, e a dica é o que faz os clientes MCP pedirem sua confirmação. Nenhuma ferramenta de escrita afirma ser idempotente. Se a confirmação é mostrada e como é mostrada depende do seu cliente MCP; mantenha a aprovação por chamada ativada para as ferramentas de escrita.
• Entrada estrita. Cada ferramenta rejeita argumentos que não conhece, para que um filtro que a API não possui nunca seja ignorado silenciosamente e um discount digitado incorretamente não possa produzir um recibo com o total errado. As ferramentas de escrita também rejeitam valores não inteiros e contatos malformados antes que qualquer coisa seja enviada.
• Sem novas tentativas cegas. O servidor nunca repete uma escrita por conta própria, exceto uma vez após um HTTP 401, onde a solicitação foi recusada por autenticação e um token novo é necessário. Se uma escrita terminar sem uma resposta definitiva (um tempo limite, uma conexão interrompida, um erro de gateway, HTTP 429, uma resposta ilegível), a ferramenta diz que o resultado é desconhecido e como verificá-lo. Cada novo recibo recebe um UUID antecipadamente; o Checkbox documenta que rejeita um recibo cujo id já existe, portanto uma nova tentativa com esse id não pode criar uma duplicata.
• Sem contornar as próprias verificações do Checkbox. close_shift não expõe a opção que ignora a verificação de que um turno é fechado pelo programa que o abriu.
• As credenciais permanecem locais. Elas são lidas das variáveis de ambiente, usadas apenas para solicitações a CHECKBOX_API_URL e nunca gravadas em stdout, stderr ou resultados de ferramentas. Redirecionamentos não são seguidos, portanto nem a chave de licença nem um corpo de solicitação podem acabar em outro host. O token de acesso vive na memória e é revogado quando o cliente MCP se desconecta (melhor esforço: um processo morto não pode fazer isso).
• Menos dados para o modelo. As ferramentas de lista retornam resumos sem contatos de clientes; o número de identificação fiscal pessoal do caixa é removido de todos os resultados. get_receipt e get_order retornam registros completos, que podem conter endereços de e-mail, números de telefone e endereços de entrega de clientes.
• Sem telemetria, sem registro de dados comerciais. O stderr recebe apenas mensagens de inicialização (problemas de configuração e um banner de uma linha com o modo) e o tipo de um erro de transporte. Solicitações e respostas nunca são registradas.

Duas coisas que o servidor não pode fazer por você. Primeiro, tudo o que uma ferramenta retorna é enviado ao modelo de IA que você usa e ao seu provedor; decida se isso é aceitável para seus dados. Segundo, nomes de mercadorias, comentários e outros textos armazenados no Checkbox chegam ao modelo como estão e podem conter instruções escritas por outra pessoa (injeção de prompt). Essa é mais uma razão para aprovar cada chamada de escrita você mesmo.

Testando com dados de teste do Checkbox

Isto é o que o Checkbox documenta; este projeto não foi executado contra isso ainda.

• Não há um host de sandbox separado. De acordo com o wiki, https://api.checkbox.ua é o único endereço tanto para testes quanto para trabalho fiscal. O que torna uma sessão um teste é o caixa e a caixa registradora com os quais você faz login.
• Um caixa de teste e uma caixa registradora de teste aparecem no painel pessoal do Checkbox automaticamente após o registro (wiki: dados de teste). Recibos de teste não são enviados ao serviço fiscal e são marcados como recibos de teste. O Checkbox os limita a 100 por mês.
• Para o caixa de teste, a senha é a mesma que o login (wiki: autorização).
• O Checkbox avisa para nunca usar um caixa ou caixa registradora de produção para testes: dados incorretos enviados ao serviço fiscal precisam ser explicados e podem levar a uma multa.

Uma primeira sessão razoável: configure o servidor com o caixa de teste, deixe CHECKBOX_ALLOW_WRITE não definido e chame get_cashier_profile. Ele deve mostrar is_test: true. Só então considere o modo de escrita, com as credenciais de teste.

Limitações

• Não verificado contra a API ao vivo. As solicitações são verificadas contra o documento OpenAPI, que descreve formatos, não comportamentos. O tratamento de respostas, textos de erro e o fluxo de status assíncrono são implementados a partir da documentação.
• Um caixa por instância do servidor, e um caixa registradora para as ferramentas que precisam da chave de licença.
• Não coberto: operações em modo offline (entrar/sair do modo offline, recibos offline), criação de relatórios X, recibos de pré-pagamento e pós-pagamento, câmbio de moedas, faturas e terminais de aquisição, edição de mercadorias, guias de remessa de serviços de entrega (ЕТТН), webhooks, relatórios estendidos, modelos de recibos.
• search_receipts não pode filtrar por status ou tipo, porque a API não possui tal parâmetro; a ferramenta retorna ambos os campos para cada recibo. Por padrão, a API retorna apenas recibos criados pelo caixa autenticado.
• A fiscalização é assíncrona. Um novo recibo ou turno retorna no status CREATED; o modelo precisa consultar get_receipt ou get_current_shift. O servidor não aguarda.
• Em um recibo de devolução, os pagamentos são enviados como valores positivos. O documento OpenAPI não especifica isso; precisa ser confirmado em uma caixa registradora de teste.
• Sem totais para a maioria das listas. A API informa um total apenas para pedidos, então o servidor só pode dizer que pode haver uma próxima página.
• Limites de taxa não são aplicados pelo servidor. O Checkbox documenta um limite de dois novos recibos por segundo por caixa registradora (exceder isso bloqueia a caixa por 5 segundos) e bloqueia visualizações repetidas do mesmo recibo em três solicitações por segundo.
• Tokens. O Checkbox documenta no máximo três tokens válidos por caixa. O servidor faz login uma vez por inicialização, faz login novamente após um HTTP 401 somente se o token tiver mais de um minuto e faz logout na desconexão; mesmo assim, um caixa que também esteja autenticado em outro lugar pode ser afetado.
• Não misture programas dentro de um turno. O Checkbox alerta que um turno aberto pela API não deve ser operado pelos aplicativos Checkbox Kasa ou Manager ao mesmo tempo.
• Tempo limite fixo de 30 segundos por solicitação.

Desenvolvimento

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 é o catálogo de operações da API que o servidor chama. tests/spec.test.ts compara com spec/checkbox-api.snapshot.json, uma cópia reduzida do documento OpenAPI oficial (apenas parâmetros, esquemas de solicitação e segurança dessas operações).
• Cada teste de ferramenta chama a ferramenta por meio de um cliente MCP real e passa cada solicitação registrada por assertMatchesSpec, que verifica o caminho, parâmetros de consulta, cabeçalhos e corpo contra esse snapshot.
• tests/e2e.test.ts inicia o servidor compilado como um processo filho via stdio contra um mock HTTP local.
• Para testar o servidor manualmente: npx @modelcontextprotocol/inspector node dist/index.js.

O servidor usa o SDK TypeScript oficial (@modelcontextprotocol/server) e zod; não há outras dependências de tempo de execução.

Issues e pull requests são bem-vindos. Para relatórios de segurança, veja SECURITY.md.

Construído por

Construído e mantido por Myrado Studio — servidores MCP personalizados, agentes de IA e automação. Precisa de um servidor MCP para o seu próprio sistema? https://myradostudio.com/en/mcp-server-development/

Licença

MIT © 2026 Myrado Studio