e-arveldaja-mcp

# e-arveldaja MCP Server

[![npm](https://img.shields.io/npm/v/e-arveldaja-mcp)](https://www.npmjs.com/package/e-arveldaja-mcp)

MCP server for the Estonian e-arveldaja (RIK e-Financials) REST API. 127 tools on the compatibility-preserving standard profile, 16 workflow prompts, 15 resources. Works with any MCP client — Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, and others.

> **⚠️ Action required if you used v0.22.0 (incoming transactions booked backwards).** A high-severity regression in **0.22.0** forced every newly created bank transaction to the "money out" direction, so **incoming** entries — owner deposits, customer receipts, refunds, and incoming inter-account transfers — were booked backwards (cash on the wrong side, moving the balance by twice the amount the wrong way). The ledger still balanced, so nothing errored. It is fixed in **0.22.1**. If you ran an e-arveldaja-mcp session while 0.22.0 was current (roughly **Sunday 2026-07-19 22:30 – Monday 2026-07-20 04:15**), any bank-statement entries created in that window are very likely wrong. Check what e-arveldaja reports as the bank-account balance against the real bank-account balance; if they differ, re-importing the affected bank statements fixes it. See the [changelog](CHANGELOG.md) for full details.
>
> **Correct standard-chart accounts (behaviour change).** Every hardcoded default account was audited against the e-arveldaja RTJ standard chart and corrected — several earlier defaults pointed at the wrong account (e.g. the dividend income-tax liability at 2540 "Kogumispensioni maksed", an FX loss at an income account). More importantly, the tools now resolve each equity/liability/financial account **by its Estonian name** against your company's actual chart, using the standard number only as a fallback, so dividend, share-capital, reserve, FX, and Lightyear postings land on the right account even on a custom or renumbered chart. If you booked with an earlier version this year, the read-only `npm run audit:legacy-accounts` script flags any entries still sitting on an old default account. See the [changelog](CHANGELOG.md) for full details.
>
> **Correct dividend legality checks.** `prepare_dividend_package` now applies ÄS § 157 clause by clause: the retained-earnings ceiling is **net-based** — the entire retained-earnings balance is distributable as net dividend, with the 22/78 income tax booking as a current-period expense on top — while the net-assets floor stays gross-based. Every response reports the largest lawful net dividend (`maximum_distributable.max_net_dividend`) and statutory `compliance_notes` (approved annual report + profit-distribution decision, TSD annex 7 deadline). The `earveldaja://tax_rules` reference now also covers profit distribution (ÄS § 157, TuMS § 50) and RPS process rules (corrections, inventory, retention). See the [changelog](CHANGELOG.md) for full details.
>
> **Guided workflow actions.** `recommend_workflow` suggests the safest accounting flow for a natural-language goal, and key workflow/batch tools return a `workflow_action_v1` envelope with `recommended_next_action`, review questions, and approval previews. `accounting_inbox` is the preferred merged entry point for workspace triage, `continue_accounting_workflow` is the preferred merged continuation tool, `receipt_batch` and `process_camt053` are the preferred mode-based import/batch entry points, and bank work has `reconcile_bank_transactions` plus `classify_bank_transactions` as mode-based entry points. Older focused tools such as `resolve_accounting_review_item`, `prepare_accounting_review_action`, `scan_receipt_folder`, `process_receipt_batch`, `parse_camt053`, `import_camt053`, `reconcile_transactions`, and `apply_transaction_classifications` are hidden from the tool list by default to keep the per-session token cost down (the merged tools route to the same internals); set `EARVELDAJA_EXPOSE_GRANULAR_TOOLS=1` to register them again. See the [changelog](CHANGELOG.md) for full details.
>
> **Opening balances (algbilanss).** e-arveldaja's own "Algbilansi kanded" (opening-balance) register isn't exposed by the REST API, so the server was otherwise blind to it. The new `import_opening_balances` tool lets you paste that register once — it's parsed, checked that total debit equals total credit, and previewed (`dry_run=true` by default) before you confirm with `dry_run=false`. Once stored per company, account balances, trial balance, the balance sheet, P&L, the annual report, and the dividend §157 legality checks all fold the opening balances in automatically. Entirely optional — without it everything still works, just without opening-balance amounts folded in. See the [changelog](CHANGELOG.md) for full details.
>
> **Active development.** This package is under active development and has not seen extensive real-world testing yet. If you encounter a bug or unexpected behaviour, please let me know via [GitHub Issues](https://github.com/iseppo/e-arveldaja-mcp/issues) or email at indrek.seppo@gmail.com.

## Disclaimer

**This is an experimental, unofficial project.** It is not affiliated with, endorsed by, or in any way officially connected to RIK (Registrite ja Infosüsteemide Keskus) or the e-arveldaja / e-Financials service.

**Use entirely at your own risk.** This software interacts with live financial data and can create, modify, confirm, and delete accounting records (invoices, journal entries, transactions, etc.). The authors accept no responsibility for any data loss, incorrect bookings, or other damages resulting from the use of this software.

By using this software you acknowledge that:
- You are solely responsible for verifying all data and operations
- You should test thoroughly on the demo server before using with live data
- This is experimental software with no warranty of any kind

## Getting an API Key

1. Log in to [e-arveldaja](https://e-arveldaja.rik.ee/)
2. Go to **Seadistused** → **Üldised seadistused** → **Lisa uus juurdepääsuluba** (Settings → General settings → Add new access token)
3. Enter any name for the token
4. Find your public IP address (e.g. at [api.ipify.org](https://api.ipify.org)) and enter it in the allowed IP field. Multiple IPs can be separated by `;`
5. Save — download the `apikey.txt` file and place it in the working directory where you run your AI assistant

If you don't have a static IP address, you will need to update the allowed IP in e-arveldaja settings whenever your IP changes.

If requests later start failing with `401 Unauthorized`, the most common cause is that your public IP changed and no longer matches the allowed IP list. Check the current public IP yourself in a browser (for example, `https://api.ipify.org`) and update the whitelist in e-arveldaja if needed.

**Never commit the `apikey.txt` file to git.**

For the demo server, set the environment variable `EARVELDAJA_SERVER=demo`.

## Setup

### 1. Add the MCP server

Most AI assistants can set this up for you — just ask:

> "Add e-arveldaja-mcp as an MCP server to this project using npx. The package is on npm."

If you prefer to do it manually:

**Claude Code:**
```bash
claude mcp add e-arveldaja -- npx -y e-arveldaja-mcp
```

**Other tools** (Cursor, Windsurf, Cline, Gemini CLI, Codex CLI, Antigravity) — add to your MCP config:
```json
{
  "mcpServers": {
    "e-arveldaja": {
      "command": "npx",
      "args": ["-y", "e-arveldaja-mcp"]
    }
  }
}
```

<details>
<summary>Config file locations by tool</summary>

| Tool | Config file |
|---|---|
| **Claude Code** | `~/.claude/settings.json` or project `.claude/settings.json` |
| **Codex CLI** | `~/.codex/config.toml` (TOML format) |
| **Gemini CLI** | `~/.gemini/settings.json` |
| **Google Antigravity** | MCP Store UI → Manage MCP Servers → raw config |
| **Cursor** | `.cursor/mcp.json` in your project |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **Cline** | VS Code settings under `cline.mcpServers` |

</details>

### 2. Add your API credentials

Put the downloaded `apikey.txt` in the working directory where you run your AI assistant. On the first start, the server detects it and offers to verify and import it into a `.env` file — either locally (just this folder) or globally (works from any folder).

You can also import manually at any time by asking your AI assistant:

> "Import my API key from apikey.txt"

For multiple companies, place multiple files (`apikey.txt`, `apikey-company2.txt`, etc.) and use `list_connections` / `switch_connection` to switch between them. Set `EARVELDAJA_DEFAULT_CONNECTION=<index or name>` to choose which company a freshly started server uses (default: index 0), and pass the optional `connection` argument on writes to have the server refuse any call aimed at a company that is not active.

### 3. Optional: define company-specific accounting rules

If your company has stable booking conventions that cannot always be derived from the ledger alone, create an optional local file:

`accounting-rules.md`

This file is human-editable Markdown, not JSON. It is meant for:
- counterparty-specific auto-booking defaults when supplier history is missing
- owner-expense VAT deduction defaults or account-specific overrides
- annual-report overrides for liability maturity and cash-flow category classification

By default these rules are stored as an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle — a directory of Markdown files (one concept per file). The untouched `accounting-rules.md` shipped with this repository is only a generic template and does not pin rules to the checkout. New stores use an opaque identity scope under the per-user config directory (`~/.config/e-arveldaja-mcp/accounting-rules/<identity-digest>`, or the platform equivalent), so different companies do not share generated rules. The scope is derived from the non-secret stable connection fingerprint rather than its mutable display lab