kitupiikki-mcp

An MCP server (agent interface) for Kitsas bookkeeping files. Lets AI agents such as Claude read your books and prepare draft vouchers in a local .kitsas file, which a human then reviews and posts in the Kitsas app.

Unofficial community project. Not affiliated with, endorsed by or supported by Kitsas Oy. Kitsas / kitupiikki is © Arto Hyvättinen and Kitsas Oy – https://github.com/artoh/kitupiikki.

Suomeksi alla ↓

Why

Small Finnish companies (one-person osakeyhtiö, associations) have a few dozen documents a month. A capable agent can do the bookkeeping, as long as it has a safe, well-defined way to talk to a real double-entry ledger that produces the statutory Finnish reports. Kitsas already does the reports (tilinpäätös, tase-erittelyt, ALV-ilmoitus, päiväkirja/pääkirja). This project gives it an agent interface.

Related MCP server: Local File Reader MCP Server

Safety model

Tools

VAT made easy for agents

Put vat_code and vat_percent on the net row and the server adds the VAT row to the VAT receivable/payable account, exactly like Kitsas does. Or give the gross amount:

{"account": 7640, "gross": 30.30, "side": "debit", "vat_code": 21, "vat_percent": 13.5}

→ 26.70 to 7640 + 3.60 to 1763 (deductible VAT). Add "vat_amount": 3.60 to match a receipt to the cent.

VAT codes: 0 no VAT · 21 deductible purchase · 11 taxable sale · 19 0 % sale (e.g. services sold outside the EU).

Install

Requires Python 3.10+.

pip install git+https://github.com/<your-account>/kitupiikki-mcp

Claude Desktop / Claude Code / any MCP client

{
  "mcpServers": {
    "kitsas": {
      "command": "kitupiikki-mcp",
      "args": ["--file", "C:\\Users\\me\\Kirjanpito\\Yritys Oy.kitsas"]
    }
  }
}

Optional: --backup-dir (default: kitupiikki-mcp-backups next to the book).

Works with the local (free) Kitsas file. Cloud books (Kitsas pilvi) are not supported — their API is not publicly available for writing.

Typical monthly workflow

1. Close Kitsas.

2. Ask the agent: "Book September: here are the bank statement and receipts."

3. The agent previews each voucher (dry_run), you confirm, it creates drafts with receipts attached.

4. Open Kitsas → Kirjaa → Luonnokset, check and save each draft (it gets a number and is posted).

5. File VAT from Kitsas as usual.

Development

pip install -e ".[test]"
pytest

Tests build a book from Kitsas's own schema (tests/luo.sql, copied unmodified from kitupiikki, GPL-3). The SQL mirrors kitsas/sqlite/routes/tositeroute.cpp and saldotroute.cpp; code tables are in src/kitupiikki_mcp/codes.py with source references.

Ideas welcome: bank statement import (CAMT/CSV) as drafts, open-item (erä) matching, reverse-charge VAT codes, salary vouchers from palkka.fi, a proper upstream API in Kitsas.

License

GPL-3.0-or-later, like Kitsas. See LICENSE.

Suomeksi

kitupiikki-mcp on MCP-palvelin, jonka avulla tekoälyagentti (esim. Claude) voi lukea Kitsaan paikallista kirjanpitotiedostoa ja tehdä siihen tositeluonnoksia. Ihminen tarkistaa ja kirjaa luonnokset Kitsaassa (Kirjaa → Luonnokset).

• Agentti ei koskaan kirjaa suoraan kirjanpitoon – vain luonnoksia.

• Ennen ensimmäistä kirjoitusta otetaan varmuuskopio, ja jokainen muutos lokitetaan.

• Kirjoitus estetään, jos Kitsas-ohjelma on auki samassa tiedostossa.

• Tositteen pitää täsmätä sentilleen, tilin on oltava tilikartassa ja päivämäärän avoimella tilikaudella.

• ALV-rivit muodostetaan automaattisesti (esim. brutto 30,30 € / 13,5 % → 26,70 + 3,60).

Epävirallinen yhteisöprojekti, ei Kitsas Oy:n tuote eikä sen tukema.