Bookiz
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SMTP_URL | No | Send invoices and archive receipts by e-mail (Brevo or any SMTP). | |
| MAIL_FROM | No | Send invoices and archive receipts by e-mail (Brevo or any SMTP). | |
| PUBLIC_URL | No | Enables receipt-upload links and invoice PDF links. | |
| BOOKIZ_TOKEN | No | Required with `--http`, at least 24 characters. Sent as a Bearer header. | |
| DATABASE_URL | No | Use this Postgres instead (Supabase, Neon, your own). | |
| BOOKIZ_DATA_DIR | No | Embedded database, receipts, PDFs. Default `~/.bookiz`. | ~/.bookiz |
| RECEIPT_ARCHIVE | No | `email` or `folder`. Default: `email` when SMTP is set. | |
| BOOKIZ_URL_TOKEN | No | Optional second secret that enables `/mcp/<secret>` for URL-only assistants. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Bookiz is the bookkeeping of one Dutch eenmanszaak (sole proprietor). You operate it for the owner.
How to work:
Start with get_overview when you do not know the state of the books. It tells you what needs attention.
Speak Dutch with the owner unless they write in another language. Amounts are euros.
Never invent a figure. Read amounts, dates and btw from the receipt or ask. If a receipt is unreadable, say so.
The engine decides the tax treatment from rules in /rules; you supply facts. If a result surprises you, call get_tax_rules and show the source instead of working around it.
Show a draft invoice to the owner and get a yes before finalize_invoice. Final invoices and filed btw periods cannot be changed, only reversed.
Ask before send_invoice and before mark_vat_return_filed. Bookiz never files with the Belastingdienst itself.
Results are calculations under published rules, not tax advice. Say so when the owner is about to rely on a number for the income tax return.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_overviewA | The state of the books right now: open btw periods and deadlines, unpaid and overdue invoices, expenses without a receipt, profit this year, an indication of what to set aside for tax, and a list of next actions. Call this first. It also prepares a draft for any recurring invoice that has come due; it never finalizes or sends anything. |
| setup_businessA | Create or update the business profile. Only pass fields that change. Name, address, KvK-nummer, IBAN and (unless the KOR applies) btw-id are legally required on invoices. kor_since is the first day of the kleineondernemersregeling (omit when the business charges btw); kor_until is the last day it applied, set only when the owner left the KOR. Neither may change how documents already booked are treated. |
| set_year_factsB | Facts about a tax year that documents cannot show. hours_criterion: did the owner work at least 1,225 hours in the business (needed for zelfstandigenaftrek). starter: entitled to startersaftrek. wage_income: gross wage from employment that year, used only to estimate how much tax to set aside. Ask the owner; do not assume. |
| save_contactA | Create a customer (omit id) or update one (pass id). Name and address are required on an invoice. vat_id is required to invoice an EU business with btw verlegd. country is an ISO code such as NL, BE, DE, US. |
| find_contactsA | Find customers by part of their name or e-mail address. Without a query it lists all of them. Check here before creating a new contact. |
| create_invoiceA | Create a draft invoice, or replace one by passing draft_id. A draft has no number and changes nothing in the books. unit_price is excluding btw. vat_code per line: high (21%, the default), low (9%), zero, exempt, eu_reverse_charge (services to a business in another EU country, btw verlegd), outside_eu (services to a customer outside the EU). Under the KOR every line is invoiced without btw automatically. Show the result to the owner before finalize_invoice. |
| finalize_invoiceA | Turn a draft into a final invoice: it gets the next consecutive number, a PDF, and counts for btw and profit. This cannot be undone, only reversed with credit_invoice. Only call after the owner approved the draft. |
| send_invoiceA | E-mail a final invoice as PDF to the customer, with a copy to the owner. Needs SMTP on the server. Ask the owner before sending; this leaves the building. |
| register_paymentA | Mark a final invoice as paid on a date (default today). Pass paid_on: null to undo a mistake. |
| credit_invoiceA | Reverse a final invoice with a creditfactuur dated today. Use this for any mistake on a final invoice, then create a correct new one. |
| list_invoicesA | List invoices, optionally for one year or one status: concept, open, "te laat" (past the due date) or betaald. |
| save_recurring_invoiceA | Create (omit id), change or stop (active: false) an invoice that repeats every 1, 3 or 12 months, for example a monthly retainer. On each date Bookiz prepares a draft, never a final invoice; get_overview reports the draft and the owner approves it as usual. |
| list_recurring_invoicesB | The invoices that repeat, with their interval and next date. |
| import_opening_stateA | Take over what is still alive when the owner switches from another bookkeeping package (Moneybird, e-Boekhouden, Jortt, a spreadsheet). Use it once, after setup_business and after creating the customers with save_contact. It does NOT copy the old administration: the owner keeps an export of the old package for seven years. switch_date: the first day the books are kept here; btw returns and reports start from that day. last_invoice_number: the year and the highest sequence number already used there, so numbering continues without a gap or duplicate (not needed when switching on 1 January). open_invoices: invoices sent from the old package that are not paid yet, with their original number and amounts. They appear as outstanding and can be paid or credited here, but do not count again for turnover or btw. assets: equipment still being depreciated, at its book value on the switch date, with the original purchase price and the remaining years. If the owner uses another package with an MCP server or export, read the figures from there; never estimate them. |
| record_expenseA | Book a business purchase from a receipt or purchase invoice. amount is the total paid including btw; vat_amount is the btw printed on the document (required for Dutch suppliers, 0 if none is shown). vat_treatment: nl (Dutch supplier, the default), eu_reverse_charge (supplier in another EU country charged no btw, e.g. Google Ireland), non_eu_reverse_charge (supplier outside the EU, e.g. a US SaaS), none (no btw involved: private seller, exempt, insurance). paid_from: business account, or private when the owner paid with private money. kind: investment for a durable asset of €450 or more excluding btw (laptop, camera); it is depreciated over useful_life_years (default 5). category: kantoor (papier, postzegels, kleine apparatuur, flexplek); software (SaaS, domeinnaam, hosting, AI-abonnement); telefoon_internet (alleen het zakelijke deel); reiskosten (trein, parkeren, taxi; eigen auto via kind "mileage"); opleiding (cursus, boeken voor het vak); verzekering (beroepsaansprakelijkheid; geen arbeidsongeschiktheidsverzekering); marketing (advertenties, website, drukwerk); advies (boekhouder, jurist, Bookiz); bankkosten (zakelijke rekening, betaalprovider); representatie (relatiegeschenk, congres, zakelijke lunch die je zelf inkoopt); eten_drinken_horeca (zakelijke lunch of diner in restaurant of café); overig (alles wat nergens anders past). Refuses a likely duplicate unless allow_duplicate is true. Afterwards, store the original with attach_receipt. |
| record_mileageA | Book business kilometres driven with the owner’s private car at the fixed rate per kilometre. Not for a company car, and not for commuting to an employer. |
| attach_receiptA | Store the original receipt or purchase invoice of an expense (JPG, PNG, WEBP, HEIC or PDF, max 10 MB). Pass exactly one source: file when the app hands you an uploaded file object, file_path when Bookiz runs on the same computer as you, url for an https download link, or content_base64. The file is e-mailed to the owner’s archive mailbox or written to the data folder; the database keeps only a SHA-256 hash. If you cannot pass the file, give the owner the upload link from record_expense. |
| void_expenseA | Cancel an expense that was booked by mistake. It stays visible with the reason. Not possible once its btw period has been filed. |
| list_expensesC | List expenses, optionally for one year or only those still missing a receipt. |
| vat_returnA | The btw-aangifte for a period (2026-Q4 or 2026-11), per rubriek in whole euros exactly as the form of Mijn Belastingdienst Zakelijk asks, with the documents behind every number, the ICP list and the deadline. Without a period it picks the oldest one that still has to be filed. The owner copies the figures into the form; Bookiz does not submit. |
| mark_vat_return_filedA | Record that the owner filed the btw-aangifte for a period. This freezes the figures and locks the period. Only call after the owner confirms the filing was actually submitted. |
| year_reportB | Profit and loss for a year and the steps to taxable profit: omzet, kosten per category, afschrijvingen, kleinschaligheidsinvesteringsaftrek, zelfstandigenaftrek, startersaftrek, MKB-winstvrijstelling, plus an indication of income tax and Zvw to set aside. These are the figures for "winst uit onderneming" in the aangifte inkomstenbelasting. |
| export_booksA | Everything for one year as JSON: business profile, invoices, expenses with receipt hashes, filed btw returns, the year report and the tax rules used. For a bookkeeper, a backup, or leaving Bookiz. |
| get_tax_rulesA | The Dutch tax figures Bookiz calculates with for a year (btw rates, KOR limit, zelfstandigenaftrek, MKB-winstvrijstelling, KIA table, kilometre rate, income tax brackets), each with its official source. Pass key for one rule including the literal quote from the source page. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 24 tools
Most tools map to distinct resources and actions, and the detailed descriptions clarify invoice, expense, VAT, contact, and reporting workflows. However, get_overview, year_report, list_invoices, and list_expenses all surface financial state or profit, so an agent may sometimes need to choose carefully among them.
The set is mostly snake_case verb_noun (create_invoice, record_expense, list_invoices, save_contact), with predictable resource suffixes. A few tools are noun-only (vat_return, year_report) and save vs create is used for upserts, but the convention remains readable and mostly consistent.
At 24 tools, this sits at the top of the rubric's 16-25 'heavy' band. The bookkeeping domain is broad enough to justify many operations, but the surface still feels large rather than tightly scoped.
Core workflows are well covered: contacts, invoice lifecycle including recurring invoices, payments and credits, expenses with receipts and mileage, VAT returns, annual reports, export, and tax rules. Gaps are modest, such as no bank reconciliation/import and limited direct editing or detail retrieval, but agents can work around them.