Skip to main content
Glama
README.md
<p align="center">
  <a href="https://boekiehouder.nl">
    <img src="docs/logo.png" alt="Bookiz" width="120">
  </a>
</p>

<h1 align="center">Bookiz</h1>

<p align="center">
  <strong>Bookkeeping for Dutch sole proprietors who send few invoices.</strong><br>
  You talk to the AI assistant you already use. Bookiz keeps the books, under tax rules you can read.
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-fa4901" alt="License: AGPL-3.0"></a>
  <a href="rules/LICENSE"><img src="https://img.shields.io/badge/tax%20rules-MIT-fa4901" alt="Tax rules: MIT"></a>
  <img src="https://img.shields.io/badge/MCP-server-0d0d0d" alt="MCP server">
  <img src="https://img.shields.io/badge/node-%E2%89%A5%2022.18-0d0d0d" alt="Node 22.18 or newer">
  <img src="https://img.shields.io/badge/tax%20year-2026-0d0d0d" alt="Tax year 2026">
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="#what-you-can-say">What you can say</a> ·
  <a href="#the-24-tools">Tools</a> ·
  <a href="#the-rules-are-data">Rules</a> ·
  <a href="#hosting">Hosting</a> ·
  <a href="https://boekiehouder.nl">Website (NL)</a>
</p>

<p align="center">
  <img src="docs/hero.png" alt="Bookiz: boekhouden voor wie weinig factureert" width="820">
</p>

> **Nederlands, kort:** Bookiz is open-source boekhouding voor eenmanszaken met
> weinig facturen. Je regelt facturen, bonnen en je btw-aangifte door met je
> eigen AI-assistent te praten. Elke belastingregel staat in deze repository,
> met de pagina van de Belastingdienst waar hij vandaan komt.

## Why this exists

If you run a one-person service business in the Netherlands, your whole
administration is a handful of invoices, a pile of receipts and four btw
returns a year. Bookkeeping software is built and priced for businesses ten
times that size. And every spring you pay someone a few hundred euros because
you no longer trust your own numbers.

Bookiz is the opposite bet:

- **Small on purpose.** No bank feeds, no quotes, no stock, no payroll. One
  small database and 24 tools.
- **No app to learn.** It is an [MCP](https://modelcontextprotocol.io) server.
  Your assistant is the interface: Claude, Codex, or any other that lets you
  add your own MCP server.
- **No AI inside.** The assistant reads the receipt and supplies facts. A
  deterministic engine applies the rules. Same input, same books.
- **Rules you can check.** Every figure is in [`rules/nl-2026.json`](rules/nl-2026.json)
  with its official source and the sentence that states it. Your bookkeeper can
  read along.
- **Yours to leave.** Self-host it for free, export everything as one file.

> **Status: 0.1, early.** The engine is tested but has run no real
> administration yet. It calculates; it does not file with the Belastingdienst
> and it is not tax advice. Rules are complete for **2026**; 2027 is open for
> booking on provisional rules until the Belastingdienst publishes the rest.

## What you can say

```text
You     Richt mijn administratie in. Ik ben Studio Voorbeeld, KvK 12345678.

You     Maak een factuur voor Klant BV: tien uur advies à 85 euro.
Bookiz  Concept: € 850,00 + € 178,50 btw = € 1.028,50. Akkoord?
You     Ja.
Bookiz  Factuur 2026-001 is definitief. Zal ik hem versturen?

You     [photo of a receipt] Lunch met de klant, zelf voorgeschoten.
Bookiz  Geboekt als K2026-003: € 54,50, privé betaald. De btw op eten en
        drinken in de horeca is niet aftrekbaar; 80% telt als kosten.

You     Hoe sta ik ervoor?
Bookiz  Btw vierde kwartaal: € 157 te betalen, vóór 31 januari.
        Eén factuur staat open. Winst dit jaar: € 606,40.
```

Your assistant writes the sentences; the numbers and the tax treatment come
from Bookiz.

## What it does

| | |
| --- | --- |
| **Invoices** | Every legally required field, consecutive numbers, PDF, e-mail. A final invoice is never edited, only reversed by a credit invoice. |
| **Expenses** | Receipts and purchase invoices, also when paid privately. Reverse-charged foreign subscriptions (rubriek 4a/4b), investments with depreciation, kilometres with your own car. |
| **Btw-aangifte** | Per rubriek in whole euros, with the documents behind every number, the ICP list and the deadline. You copy the figures into Mijn Belastingdienst Zakelijk. |
| **KOR** | Invoices without btw, costs including btw, turnover tracked against the € 20.000 limit. The invoice that would cross it is refused. |
| **Year report** | Profit, kleinschaligheidsinvesteringsaftrek, zelfstandigenaftrek, startersaftrek, MKB-winstvrijstelling, and what to set aside for income tax and Zvw, also next to a job. |
| **Receipts** | The original goes to your own mailbox or a folder. The database keeps a SHA-256 hash, not the file. |
| **Recurring invoices** | A monthly, quarterly or yearly invoice becomes a draft on its date. Nothing is final without you. |
| **Switching** | Coming from Moneybird, another package or a spreadsheet: take over your customers, unpaid invoices, assets and invoice numbering. Old years stay in your export. |
| **Export** | A whole year as one JSON file, for your bookkeeper or for leaving. |

## Quick start

Local, on your own computer, with nothing to install but Node.js 22.18 or newer:

```bash
git clone https://github.com/meestierolff/bookiz.git
cd bookiz
npm install
```

Add it to your assistant as a local MCP server.

**Claude Code**

```bash
claude mcp add bookiz -- node /absolute/path/to/bookiz/src/cli.ts
```

**Claude Desktop** (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "bookiz": { "command": "node", "args": ["/absolute/path/to/bookiz/src/cli.ts"] }
  }
}
```

Then say: *“Richt mijn administratie in.”*

Your data lives in `~/.bookiz`: an embedded Postgres, your receipts and your
invoice PDFs. Back that folder up. The embedded database serves one process at
a time; a second assistant on the same folder is refused with a clear message
instead of corrupting your books. To use several assistants at once, run the
[remote server](#remote-server).

## The 24 tools

| Tool | What it does |
| --- | --- |
| `get_overview` | Where you stand: open btw periods and deadlines, unpaid invoices, missing receipts, profit, what to set aside, next actions |
| `setup_business` | Business profile: name, address, KvK, btw-id, IBAN, KOR period, filing frequency |
| `set_year_facts` | Urencriterium, startersaftrek and wage income for a year |
| `save_contact` · `find_contacts` | Customers |
| `create_invoice` | A draft invoice, with totals and the remarks the law requires |
| `finalize_invoice` | Number it, lock it, make the PDF |
| `send_invoice` | E-mail the PDF to the customer, copy to you |
| `register_payment` | Mark an invoice paid |
| `credit_invoice` | Reverse a final invoice |
| `list_invoices` | By year or status |
| `save_recurring_invoice` · `list_recurring_invoices` | Invoices that repeat every 1, 3 or 12 months |
| `import_opening_state` | Switch from another package: numbering, unpaid invoices, assets |
| `record_expense` | Book a receipt or purchase invoice |
| `record_mileage` | Business kilometres with your own car |
| `attach_receipt` | Archive the original document |
| `void_expense` | Cancel a mistaken expense |
| `list_expenses` | By year, or only those without a receipt |
| `vat_return` | The btw-aangifte for a period, per rubriek |
| `mark_vat_return_filed` | Freeze a period after you filed it |
| `year_report` | From turnover to taxable profit, plus the tax indication |
| `export_books` | Everything for one year |
| `get_tax_rules` | The figures in use, with source and quote |

Every change is written to an audit log. Mistakes are corrected with a new
document, never by editing an old one.

## The rules are data

```json
"zelfstandigenaftrek": {
  "title": "Zelfstandigenaftrek",
  "value": 1200,
  "unit": "EUR",
  "source": "https://www.belastingdienst.nl/…/zelfstandigenaftrek-2026",
  "quote": "Dan is de zelfstandigenaftrek in 2026 een bedrag van € 1.200."
}
```

[`rules/nl-2026.json`](rules/nl-2026.json) holds all 21 rules the engine uses:
btw rates, the KOR limit, the KIA table, income tax brackets, heffingskortingen
and more. The engine refuses to calculate for a year without a rule file; it
never extrapolates.

Found a wrong figure? Open an issue or a pull request against the rule file.
See [rules/README.md](rules/README.md). The rules are MIT-licensed so anyone can
reuse them.

## Receipts: from your phone to the archive

An MCP tool receives text, not files, and assistants differ in what they pass on:

| Where you are | What happens |
| --- | --- |
| Local assistant (Claude Code, Claude Desktop, Codex) | The assistant passes the file path; Bookiz reads the file |
| ChatGPT with a remote server | `attach_receipt` declares `openai/fileParams`, so ChatGPT can hand over a download link to your upload |
| Any other assistant | The assistant reads the photo and books the expense; Bookiz returns a one-tap upload link for the original |

The last row always works. The ChatGPT route is built from OpenAI's
documentation and has not been tested against ChatGPT itself.

With `RECEIPT_ARCHIVE=email` the original is mailed with a fixed subject:
`[Bookiz bon] K2026-001 · date · vendor · amount`. Self-hosted, it goes to the
address you set as `archive_email` (or your business `email`). In Cloud it
always goes to the address you sign in with, the only one Bookiz has proof is
yours. You must keep receipts for seven years, so that mailbox is now part of
your administration.

## Hosting

| | Self-host | Cloud | Done for you |
| --- | --- | --- | --- |
| Price | Free | € 99 per year excl. btw, first 30 days free | € 399 per year excl. btw for the first 50, then € 499 |
| What | Everything in this repository | We host it; your assistant signs in with OAuth | Cloud, plus a bookkeeper who files your btw returns and income tax return |
| Available | Now | **Opening soon** | **Presale, not live yet** |

Details on [boekiehouder.nl](https://boekiehouder.nl/#prijzen). Switching per
1 January is explained step by step on
[boekiehouder.nl/overstappen](https://boekiehouder.nl/overstappen/).

### How Cloud is built

The hosted version is this same repository: `src/cloud/` plus one Vercel
function. Supabase provides Postgres, accounts and the OAuth server that
assistants sign in through. Every customer has a Postgres schema of their own;
the engine is pointed at one schema and cannot name another. `scripts/cloud-e2e.mjs`
checks the whole flow against a deployment, including that two customers see
nothing of each other.

### Remote server

For assistants that do not run on your computer:

```bash
export BOOKIZ_TOKEN=$(openssl rand -hex 24)
export PUBLIC_URL=https://bookiz.example.com
node src/cli.ts --http        # or: docker compose up -d
```

Put it behind HTTPS on port 443. Clients that can send a header (Claude Code,
Codex) use `https://bookiz.example.com/mcp` with `Authorization: Bearer <token>`.

claude.ai, ChatGPT and Grok only accept OAuth or an unauthenticated URL for
user-added servers. Until Bookiz has OAuth they can connect to
`https://bookiz.example.com/mcp/<url-secret>`, but only if you switch that on by
setting a second secret, `BOOKIZ_URL_TOKEN`. It is off by default.

**That URL is a password.** It can end up in logs and browser history, which is
why the MCP specification advises against secrets in URLs. So it is a separate
secret from `BOOKIZ_TOKEN`: you can rotate it without touching your other
clients, and it cannot be used to forge receipt or invoice links. If you use
it, turn off or redact access logging for `/mcp/*` on your reverse proxy.

| Variable | Purpose |
| --- | --- |
| `BOOKIZ_DATA_DIR` | Embedded database, receipts, PDFs. Default `~/.bookiz` |
| `DATABASE_URL` | Use this Postgres instead (Supabase, Neon, your own) |
| `BOOKIZ_TOKEN` | Required with `--http`, at least 24 characters. Sent as a Bearer header |
| `BOOKIZ_URL_TOKEN` | Optional second secret that enables `/mcp/<secret>` for URL-only assistants |
| `PUBLIC_URL` | Enables receipt-upload links and invoice PDF links |
| `SMTP_URL`, `MAIL_FROM` | Send invoices and archive receipts by e-mail (Brevo or any SMTP) |
| `RECEIPT_ARCHIVE` | `email` or `folder`. Default: `email` when SMTP is set |

On Supabase, use the session pooler connection string. Bookiz creates its
tables on first start and turns on row level security, so Supabase's
auto-generated web API cannot read them.

## Known limits

- **2027 is provisional.** The Belastingdienst had not published 2027 figures
  on 16 November 2026. Invoices, expenses and btw returns work in 2027 on the
  rules that carry no year; the kilometre rate, the year report and the tax
  estimate for 2027 wait for the published figures.
- **Switching is new** and was built from the rules, not from a real export of
  another package. Check the outstanding amount after importing.
- Invoice basis (factuurstelsel) only; no kasstelsel, no margin schemes, no
  goods across borders, no private-use corrections (rubriek 1d).
- The 80% rule is always used for limited-deductible costs, never the threshold.
- The tax estimate covers box 1, heffingskortingen and Zvw for one person below
  AOW age. No partner, mortgage, box 3 or allowances.
- No balance sheet: Bookiz does not know your bank balance.
- The KOR is one period (`kor_since` to `kor_until`); leaving and joining again
  later is not supported. The filing frequency (month or quarter) cannot change
  once expenses or returns exist.
- A btw period that has been filed cannot be reopened. Corrections go through
  the next return or a suppletie, outside Bookiz.
- Tested against the MCP SDK client over stdio and HTTP, on embedded and real
  Postgres. Not yet tested against the real claude.ai, ChatGPT and Grok apps.

## Development

```bash
npm run verify      # typecheck, rule-file check, tests, site build
npm test            # tests only, against an in-memory Postgres
npm run web:build   # static site into web/dist; prices and links in web/site.json
```

Built with heavy use of AI coding assistants, and reviewed and tested as such:
the tax examples in the tests are calculated by hand against the published
tables, and every figure has to carry its source. If you find a wrong number,
that is the most valuable issue you can open.

## License

Engine: [AGPL-3.0](LICENSE). Tax rules in `/rules`: [MIT](rules/LICENSE).
"Bookiz" is a name of its maintainers; a fork needs its own.

TDQS

A3.6/5.0

Scored across 24 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues