checkbox-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@checkbox-mcp Show yesterday's receipts and the total by payment form."
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.
checkbox-mcp
An MCP server for the API of Checkbox, a Ukrainian software cash register (ПРРО). It lets an AI assistant such as Claude answer questions about receipts, shifts, X/Z reports, goods and orders of your organization, and, only if you explicitly allow it, open and close shifts and create fiscal receipts.
Українською: README.uk.md
Unofficial. This project is not affiliated with or endorsed by Checkbox. "Checkbox" is a trademark of its owner. Use it at your own risk: receipts created through the write tools are real fiscal documents.
Status: 0.1.0, not yet verified on a live cash register. The server is built from the official OpenAPI document (version 2.108.3) and the public Checkbox wiki. All tests run against a mocked HTTP layer and check every request against a snapshot of that OpenAPI document. Nobody has run it against the real Checkbox API yet, neither with a test cashier nor with a production one. See Limitations.
What is a ПРРО, and what is Checkbox?
In Ukraine most businesses that sell to consumers have to register each sale with the State Tax Service (ДПС). The device or program that does this is a "registrar of settlement operations" (РРО). A ПРРО is the software variant: instead of a certified hardware cash register, a program signs every receipt with the cashier's electronic signature, sends it to the tax service and gets a fiscal number back. Work is organized in shifts (зміна): a cashier opens a shift, issues receipts, and closes the shift with a Z-report, the daily summary that goes to the tax service. Checkbox is one such ПРРО service; it offers web and mobile apps and a REST API, which is what this server talks to.
Related MCP server: moysklad-mcp-ru
Quick start
You need Node.js 20 or newer and the credentials of a Checkbox cashier. To try the server out, use the test cashier and test cash register that Checkbox creates for every account (see Trying it with Checkbox test data).
Not on npm yet. Until the first release is published, the
npx -y @myradostudio/checkbox-mcpcommands below will not work. Run the server from source instead:git clone https://github.com/myradostudio/checkbox-mcp, thennpm installandnpm run buildin that folder, and use"command": "node"with"args": ["/absolute/path/to/checkbox-mcp/dist/index.js"]in the configurations below.
Claude Desktop
Add the server to claude_desktop_config.json (Settings → Developer → Edit 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"
}
}
}
}If the server does not start on Windows, use "command": "cmd" and "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-mcpCursor
Add the same block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"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"
}
}
}
}Any other MCP client that can start a local stdio server works the same way: run npx -y @myradostudio/checkbox-mcp with the environment variables below.
Then ask, for example:
"Which cashier are you signed in as, and is a shift open?"
"Show yesterday's receipts and the total by payment form."
"Find the Z-reports for last week and print the latest one."
"Is the cash register online? How many offline codes are left?"
Configuration
The server is configured with environment variables only. It validates them at startup and exits with an explanation on stderr if something is missing.
Variable | Required | Default | Purpose |
| one sign-in method | Cashier PIN code. The sign-in method Checkbox recommends. Needs | |
| one sign-in method | Cashier login. Used with | |
| with the login | Cashier password. | |
| see purpose | License key of the cash register. Required for PIN sign-in, for write mode, and for the tools that report on "this" cash register ( | |
| no |
| API origin. Must be |
| no | off | Set to |
The PIN code and the license key are shown in the Checkbox personal cabinet, in the cashier and cash register sections. If both a PIN code and a login/password pair are set, the PIN code is used.
Tools
Money amounts are integers in kopecks (13550 means 135.50 UAH) and quantities are integers in thousandths (1000 means 1 piece, 2250 means 2.25 kg), exactly as in the Checkbox API. The server tells the model so.
Read tools (always available)
Tool | What it returns | API call |
| The signed-in cashier, permissions, test flag, and the organization |
|
| Cash registers with fiscal number, address, online/offline mode, open shift |
|
| One cash register by id, or the one the license key belongs to |
|
| Available offline fiscal codes and time spent offline |
|
| The open shift of the cashier with its running balance |
|
| Shifts of the cashier, or of the cash register |
|
| One shift in full, including its Z-report once closed |
|
| Receipts by period, fiscal number, barcode, shift, cash register, branch |
|
| One receipt as JSON, or as printable text |
|
| X- and Z-reports with totals per payment form |
|
| One report as JSON, or as printable text |
|
| The periodical report for a date range, as text |
|
| Goods from the Checkbox catalogue with prices and tax rates |
|
| Tax rates configured for the organization |
|
| Orders (draft receipts placed by an external system) |
|
| One order in full, including customer delivery details |
|
List tools return compact summaries and a pagination block. The page size defaults to 25 and is capped at 100 (50 for cash register shifts, the limit of that endpoint); next_offset tells the model how to continue.
Write tools (only with CHECKBOX_ALLOW_WRITE=1)
Tool | What it does | API call |
| Opens a shift on the cash register of the license key |
|
| Closes the current shift and creates its Z-report |
|
| Creates and fiscalizes a sale receipt |
|
| Creates and fiscalizes a return receipt |
|
| Puts cash into the register or takes it out |
|
| E-mails a copy of a receipt |
|
| Sends a copy of a receipt by SMS/Viber (a Checkbox service billed separately) |
|
A receipt is a fiscal document. Once created it cannot be edited or deleted; a mistake can only be compensated with a separate return receipt. The same goes for an opened or closed shift.
Safety model
Fiscal receipts are legal documents, so the server is conservative by design.
Read-only unless you opt in. Without
CHECKBOX_ALLOW_WRITE=1the write tools are not registered at all: the model cannot see or call them. Every read tool issues onlyGETrequests, and a test enforces that.Honest annotations. Read tools carry
readOnlyHint: true. Tools that create fiscal state (open_shift,close_shift, the three receipt tools) carrydestructiveHint: true: strictly speaking they add data, but the result cannot be undone, and the hint is what makes MCP clients ask you for confirmation. No write tool claims to be idempotent. Whether and how confirmation is shown is up to your MCP client; keep per-call approval switched on for the write tools.Strict input. Every tool rejects arguments it does not know, so a filter the API does not have is never silently ignored and a misspelled
discountcannot produce a receipt with the wrong total. Write tools also reject non-integer amounts and malformed contacts before anything is sent.No blind retries. The server never repeats a write on its own, except once after an HTTP 401, where the request was refused for authentication and a fresh token is needed. If a write ends without a definite answer (a timeout, a broken connection, a gateway error, HTTP 429, an unreadable response), the tool says that the outcome is unknown and how to check it. Every new receipt gets a UUID up front; Checkbox documents that it rejects a receipt whose id already exists, so a retry with that id cannot create a duplicate.
No bypass of Checkbox's own checks.
close_shiftdoes not expose the option that skips the check that a shift is closed by the program that opened it.Credentials stay local. They are read from environment variables, used only for requests to
CHECKBOX_API_URL, and never written to stdout, stderr or tool results. Redirects are not followed, so neither the license key nor a request body can end up on another host. The access token lives in memory and is revoked when the MCP client disconnects (best effort: a killed process cannot do that).Less data to the model. List tools return summaries without customer contacts; the cashier's personal tax number is removed from every result.
get_receiptandget_orderdo return full records, which can contain customer e-mail addresses, phone numbers and delivery addresses.No telemetry, no logging of business data. stderr gets only startup messages (configuration problems and a one-line banner with the mode) and the type of a transport error. Requests and responses are never logged.
Two things the server cannot do for you. First, whatever a tool returns is sent to the AI model you use and to its provider; decide whether that is acceptable for your data. Second, names of goods, comments and other text stored in Checkbox reach the model as-is and could contain instructions written by someone else (prompt injection). That is one more reason to approve every write call yourself.
Trying it with Checkbox test data
This is what Checkbox documents; this project has not been run against it yet.
There is no separate sandbox host. According to the wiki,
https://api.checkbox.uais the single address for both testing and fiscal work. What makes a session a test is the cashier and the cash register you sign in with.A test cashier and a test cash register appear in the Checkbox personal cabinet automatically after registration (wiki: test data). Test receipts are not sent to the tax service and are marked as test receipts. Checkbox limits them to 100 per month.
For the test cashier the password is the same as the login (wiki: authorization).
Checkbox warns never to use a production cashier or cash register for testing: incorrect data sent to the tax service has to be explained and can lead to a fine.
A reasonable first session: configure the server with the test cashier, leave CHECKBOX_ALLOW_WRITE unset, and call get_cashier_profile. It should show is_test: true. Only then consider write mode, with the test credentials.
Limitations
Not verified against the live API. Requests are checked against the OpenAPI document, which describes shapes, not behaviour. Response handling, error texts and the asynchronous status flow are implemented from the documentation.
One cashier per server instance, and one cash register for the tools that need the license key.
Not covered: offline mode operations (going offline/online, offline receipts), creating X-reports, prepayment and post-payment receipts, currency exchange, invoices and acquiring terminals, editing goods, delivery-service waybills (ЕТТН), webhooks, extended reports, receipt templates.
search_receiptscannot filter by status or type, because the API has no such parameter; the tool returns both fields for each receipt. By default the API returns only receipts created by the signed-in cashier.Fiscalization is asynchronous. A new receipt or shift comes back in status
CREATED; the model has to pollget_receiptorget_current_shift. The server does not wait.In a return receipt, payments are sent as positive amounts. The OpenAPI document does not spell this out; it has to be confirmed on a test cash register.
No totals for most lists. The API reports a total only for orders, so the server can only say that there may be a next page.
Rate limits are not enforced by the server. Checkbox documents a limit of two new receipts per second per cash register (exceeding it blocks the register for 5 seconds) and blocks repeated views of the same receipt at three requests per second.
Tokens. Checkbox documents at most three valid tokens per cashier. The server signs in once per start, signs in again after an HTTP 401 only if its token is older than a minute, and signs out on disconnect; even so, a cashier who is also signed in elsewhere may be affected.
Do not mix programs within a shift. Checkbox warns that a shift opened through the API must not be operated from the Checkbox Kasa or Manager apps at the same time.
Fixed 30-second timeout per request.
Development
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.uasrc/endpoints.tsis the catalogue of API operations the server calls.tests/spec.test.tscompares it withspec/checkbox-api.snapshot.json, a reduced copy of the official OpenAPI document (parameters, request schemas and security of those operations only).Every tool test calls the tool through a real MCP client and passes each recorded request through
assertMatchesSpec, which checks the path, query parameters, headers and body against that snapshot.tests/e2e.test.tsstarts the built server as a child process over stdio against a local HTTP mock.To poke at the server by hand:
npx @modelcontextprotocol/inspector node dist/index.js.
The server uses the official TypeScript SDK (@modelcontextprotocol/server) and zod; there are no other runtime dependencies.
Issues and pull requests are welcome. For security reports see SECURITY.md.
Built by
Built and maintained by Myrado Studio — custom MCP servers, AI agents and automation. Need an MCP server for your own system? https://myradostudio.com/en/mcp-server-development/
License
MIT © 2026 Myrado Studio
Available Tools
16 toolsget_cashier_profileWho am I: cashier and organizationARead-onlyIdempotent
Returns the cashier this server is signed in as: name, permissions, signature type, whether it is a test cashier (is_test), and the organization (title, EDRPOU, tax number, VAT status, offline and SMS settings). Call this first to learn whose data the other tools will show.
Inputs: no named parameters.
get_cash_registerGet a cash registerARead-onlyIdempotent
Returns one cash register (ПРРО). With cash_register_id: full details including offline_mode (true means the register works offline) and the open shift. Without it: the register that CHECKBOX_LICENSE_KEY belongs to, including its title, address, has_shift, is_test and the numbers of the last documents.
Inputs: cash_register_id.
get_current_shiftCurrent shift of the cashierARead-onlyIdempotent
Returns the active shift (зміна) of the signed-in cashier: status, opening time, cash register, running balance (cash and card sales, returns, service cash in/out) and per-tax totals. Tells you when the cashier has no open shift.
Inputs: no named parameters.
get_offline_statusOffline mode statusARead-onlyIdempotent
Reports how the cash register behind CHECKBOX_LICENSE_KEY stands with offline mode: how many offline fiscal codes are available and whether that is enough, plus the offline sessions and total offline time, optionally limited to a period. Checkbox documents a limit of 36 hours offline in a row and 168 hours per month. Durations are passed through as the API returns them.
Inputs: to_date, from_date.
get_orderGet an orderARead-onlyIdempotent
Returns one order in full: status, payment, the receipt draft with goods and payments, and the delivery details. The result contains personal data of the customer (name, phone number, address); do not repeat it unless the user asks for it.
Inputs: order_id (required), whole_organization.
get_periodical_reportPeriodical report for a date rangeARead-onlyIdempotent
Returns the periodical report (періодичний звіт) of the cash register behind CHECKBOX_LICENSE_KEY for a date range, as printable text: totals built from the Z-reports of the period, by tax rate and payment form, returns, cash in the register and each Z-report with its number and date. The API offers this report as text only.
Inputs: to_date (required), from_date (required), short.
get_receiptGet a receiptARead-onlyIdempotent
Returns one receipt (чек). format "json": the full record with goods, payments, taxes, discounts, fiscal number, status and the link to the tax service (tax_url). format "text": the receipt exactly as it is printed. A receipt that was created a moment ago can answer "still being created"; retry after a second.
Inputs: receipt_id (required), format.
get_reportGet an X or Z reportARead-onlyIdempotent
Returns one X- or Z-report. format "json": the full record with totals per payment form and per tax rate, receipt counts, rounding and cash balance. format "text": the report exactly as it is printed.
Inputs: report_id (required), format.
get_shiftGet a shiftARead-onlyIdempotent
Returns one shift (зміна) in full: status, cashier, cash register, balance, per-tax totals, the opening and closing transactions and the embedded Z-report once the shift is closed.
Inputs: shift_id (required).
list_cash_registersList cash registersARead-onlyIdempotent
Lists the cash registers (ПРРО) available to the cashier, each with its fiscal number, address, branch, online/offline mode and the currently open shift if there is one. Use the returned ids to filter receipts and reports.
Inputs: limit, in_use, offset, fiscal_number.
list_ordersList ordersARead-onlyIdempotent
Lists orders (замовлення): draft receipts that an external system created in Checkbox, to be fiscalized by a courier after delivery and payment. Returns status, payment state and method, and the linked receipt id. Customer delivery details are left out here; get_order returns them.
Inputs: limit, offset, statuses, newest_first, +4 more.
list_reportsList X and Z reportsARead-onlyIdempotent
Lists X-reports (interim, non-fiscal) and Z-reports (end of shift) with receipt counts, cash balance and totals per payment form. Filter by period, shift, cash register, serial number or report type. Use get_report for tax breakdowns or the printable text.
Inputs: limit, offset, serial, to_date, +5 more.
list_shiftsList shiftsARead-onlyIdempotent
Lists shifts (зміни) with status, open and close times, balance and the Z-report reference. scope "cashier" (default) lists shifts of the signed-in cashier; scope "cash_register" lists shifts of the cash register behind CHECKBOX_LICENSE_KEY, whoever opened them (page size capped at 50). Use get_shift for the full record.
Inputs: limit, scope, offset, to_date, +3 more.
list_taxesList tax ratesARead-onlyIdempotent
Lists the tax rates configured for the organization: numeric code, letter symbol, label, rate and extra rate in percent, and whether the tax is included in the price. The numeric code is what a receipt line refers to in its tax list.
Inputs: no named parameters.
search_goodsSearch the goods catalogueARead-onlyIdempotent
Searches the goods catalogue (номенклатура) kept in Checkbox. Returns code, name, price in kopecks, barcode, UKTZED code, group, tax rates and stock count where the organization tracks it. The catalogue can be empty when the organization does not keep its goods in Checkbox.
Inputs: limit, query, offset, group_id.
search_receiptsSearch receiptsARead-onlyIdempotent
Finds receipts (чеки) by period, fiscal number, barcode, shift, cash register or branch. Returns a summary per receipt: type (SELL, RETURN, SERVICE_IN, SERVICE_OUT, ...), status (DONE means fiscalized), fiscal number, totals, goods and payments. The API has no filter by status or type, so filter the returned rows yourself. By default only receipts created by the signed-in cashier are returned. Use get_receipt for the full record.
Inputs: limit, offset, barcode, to_date, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct resource and action: cash registers, cashier profile, taxes, offline status, shifts, receipts, reports, goods, and orders. The only apparent overlap (get_current_shift vs list_shifts/get_shift) is resolved by descriptions that specify active shift, list, and full record respectively.
All 16 tools use consistent snake_case with clear verb_noun patterns (get_, list_, search_). No mixed conventions or vague names are present.
16 tools is slightly above the typical 3–15 range, but the surface is well organized by resource and each tool appears to serve a distinct query need. There is no obvious redundancy, though the count is on the heavier side.
The tool surface is entirely read-only: no create, update, delete, open/close shift, create/fiscalize receipt, or manage goods/orders operations. For a Checkbox fiscalization server, these are significant gaps that would block common agent workflows.
Maintenance
Related MCP Connectors
Malaysian SME accounting, e-Invoice and payroll for your AI. 95 tools; writes are approved drafts.
Read Tillhub products, stock, transactions, customers and retail reports from your AI assistant.
Query your books, company data, business health, and ship invoices from your AI assistant.
Read orders, sales reports, stock and reservations; add customers, update products in Dotypos.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with SmartKasa Ukrainian POS system through natural language, managing shops, products, inventory, sales receipts, employees, and fiscal reports with full API coverage.1MIT
- AlicenseAqualityBmaintenanceProvides AI assistants with direct access to the Moysklad (МойСклад) JSON API for reading inventory, products, orders, and reports, and creating/posted documents with safety controls.3651 PyPI3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to query a retail and food-service point-of-sale database through predefined business tools for sales summaries, top products, margins, stagnant inventory, cash reconciliation, and optional stock adjustments, returning formatted markdown answers.MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to query and manage self-hosted accounting data—invoices, balances, and books—through natural language, with read-only tools by default and optional scoped write operations.3024 PyPI1AGPL 3.0