E Arveldaja MCP

e-arveldaja MCP Server

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

Safer bank confirmations and stricter owner expenses (0.38.0, behaviour change). A payment whose text names exactly one invoice or order number can now be confirmed through the guided approval flow, and payments that match several invoices are reported instead of silently skipped. The guided Wise import picks an account automatically only when it is recognisably the Wise account, otherwise it asks. An owner-paid expense is refused before anything is written when its expense or owner-debt account has dimensions and none is given (pass expense_account_dimension_id / payable_account_dimension_id). Duplicate transfer rows are deleted only through a fresh reconciliation plan, and earlier Lightyear drafts are no longer offered for confirmation unseen. See the changelog for full details.

Year-end close now follows RIK's method (0.26.0, behaviour change). execute_year_end_close no longer zeroes revenue and expense accounts into 2970 (that broke e-arveldaja's own income statement). It books RIK's two entries from the guide "Äriühingu majandusaasta lõpetamiskanded e-arveldajas": D 9000 "Arvestuslik koondtulemus" / K 2970 on 31 December and D 2970 / K 2960 (optionally part to reserve capital) on 1 January. Entries you already booked by hand — under any document number, on 1 January or later in the next year, plus the old YECL-YYYY closes — are detected and never booked twice; a partial, reversed, duplicate or mismatched entry is reported for manual review. Also in 0.26.0: the month-end checklist evaluates overdue invoices as of today while the month is open, attach_document refuses to replace an existing source document unless replace_existing: true, Lightyear sells book the cash the statement shows, and Wise import no longer changes confirmed purchase invoices. See the changelog for full details.

⚠️ 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). Balances and reports use the API's INITIAL journals automatically, with their original dates, clients and dimensions. No local import is needed. Draft, deleted or empty API openings are disclosed; multiple active openings require review. See the changelog for 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. Alternatively, enter 0.0.0.0/0 to allow access from any IP address — convenient for laptops or changing IPs, but less secure, since then the apikey.txt file alone is enough to access your data.

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"] } } }

Config file locations by tool

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= 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 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/ , 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 label. Changing a connection label does not move its accounting-rule store. Existing data-bearing project stores and older unscoped global stores remain in place for backward compatibility. Two environment variables continue to override the location exactly:

• EARVELDAJA_RULES_DIR=/path/to/bundle — point the bundle at a stable per-company path (e.g. `~/.con