e-arveldaja MCP Server

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 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 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 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 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 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 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
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) 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:

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:

{
  "mcpServers": {
    "e-arveldaja": {
      "command": "npx",
      "args": ["-y", "e-arveldaja-mcp"]
    }
  }
}

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.

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