E Arveldaja MCP Server

e-arveldaja MCP Server

MCP server for the Estonian e-arveldaja (RIK e-Financials) REST API. 123 tools, 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

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/<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 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. ~/.config/e-arveldaja-mcp/<company>/accounting-rules). Recommended when you run several companies.
• EARVELDAJA_RULES_FILE=/path/to/accounting-rules.md — opt into the legacy single-file format: rules stay in that one file (no bundle, no migration). In the default bundle mode, an existing accounting-rules.md next to the bundle is instead migrated into it non-destructively on first write.

The bundle is also browsable as MCP resources under earveldaja://accounting_knowledge. When several MCP clients share one bundle directory, concurrent rule writes are serialized with a lock file so the index never drifts out of sync with the concepts.

4. Optional: import opening balances (algbilanss)

e-arveldaja's own "Algbilansi kanded" (opening-balance) register isn't exposed by the REST API, so the MCP server can't see it unless you paste it in once. Copy the register from the e-arveldaja UI and ask your AI assistant:

"Import these opening balances into e-arveldaja-mcp" (paste the Algbilansi kanded text)

The import_opening_balances tool parses the pasted register, checks that total debit equals total credit, and previews the result (dry_run=true by default) before you confirm with dry_run=false. Once stored, 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. This step is entirely optional — without it, everything still works, just without opening-balance amounts folded in.

Trimming the tool surface

The tool list is sent into the model's context on every session, so it is a fixed per-session token cost. Several feature groups are opt-out — they are registered by default but can be dropped when a deployment does not use them:

• EARVELDAJA_DISABLE_LIGHTYEAR=1 — drops the Lightyear investment tools (book_lightyear_*, parse_lightyear_*, lightyear_portfolio_summary) and the lightyear-booking prompt. Use it when the company does not track investments.
• EARVELDAJA_DISABLE_TAX_TOOLS=1 — drops the Estonian tax helpers (check_vat_registration_threshold, prepare_dividend_package, create_owner_expense_reimbursement, check_tax_free_limits) and the VAT-threshold prompt. The statutory tax-rules advice behind suggest_booking is unaffected. Use it when you never run VAT-threshold/dividend/reimbursement/tax-free-limit workflows.
• EARVELDAJA_DISABLE_REFERENCE_ADMIN=1 — drops the reference-data admin tools that create/update/delete bank accounts and invoice series and update invoice settings (plus the single-record get_bank_account/get_invoice_series reads). The list_*/get_invoice_info/get_vat_info reads stay. Use it when the chart of accounts, bank accounts, and invoice series are already set up and managed in the e-arveldaja UI.
• EARVELDAJA_DISABLE_ANNUAL_REPORT=1 — drops the year-end tools (prepare_year_end_close, generate_annual_report_data, execute_year_end_close). Use it for the bulk of the year; re-enable at closing time.
• EARVELDAJA_DISABLE_SALES=1 — drops the sales-invoicing side: the 11 sale-invoice tools, create_recurring_sale_invoices, and receivables aging (compute_receivables_aging). Payables aging and all purchase-invoice tools stay. Use it for purchase-side-only bookkeeping.
• EARVELDAJA_DISABLE_PRODUCTS=1 — drops the product-catalog tools (list/get/create/update/deactivate/reactivate/delete_product). Products are chiefly the sale-invoice line-item catalog (purchase items key on cl_purchase_articles_id, though they can also carry an optional products_id), so a DISABLE_SALES deployment usually sets this too. It only removes catalog management — creating either invoice type still works — so the flags stay independent.

A lean purchase-side-only deployment with every disable flag set (incl. Lightyear) lands near 80 tools instead of the default 123. Conversely, EARVELDAJA_EXPOSE_GRANULAR_TOOLS=1 and EARVELDAJA_EXPOSE_SETUP_TOOLS=1 register the hidden granular and credential-management tools when you need them.

Confirmed supplier history still wins over local rules for purchase booking defaults.

export EARVELDAJA_API_KEY_ID=...
export EARVELDAJA_API_PUBLIC_VALUE=...
export EARVELDAJA_API_PASSWORD=...

git clone https://github.com/iseppo/e-arveldaja-mcp.git
cd e-arveldaja-mcp
npm install && npm run build
# Then use: "node", "/path/to/e-arveldaja-mcp/dist/index.js" instead of npx

Workflows (MCP Prompts)

The server includes 16 built-in workflow prompts that any MCP client can discover and use. These guide the AI through multi-step accounting tasks:

Claude Code also has these as slash commands: /vat-registration-threshold, /accounting-inbox, /resolve-accounting-review, /prepare-accounting-review-action, /book-invoice, /receipt-batch, /import-camt, /import-wise, /classify-unmatched, /reconcile-bank, /month-end, /new-supplier, /company-overview, /lightyear-booking, /setup-credentials, /setup-e-arveldaja.

Usage Examples

Once the MCP server is connected, just talk to your AI assistant in natural language:

Start from one inbox-style overview

"Scan this workspace and tell me what can be done automatically, what needs one decision, and what needs accountant review"

This is the recommended first step for non-accountants. The assistant will use the accounting inbox flow to detect likely CAMT files, Wise CSV exports, and receipt folders, propose safe dry-run steps in the right order, and ask only the smallest missing follow-up questions with recommended defaults first.

Accounting inbox and workflow recommendation responses include a workflow block with done, needs_decision, needs_review, recommended_next_action, available_actions, and approval_previews so clients can continue from one compact next step instead of choosing among all tools manually.

Enter purchase invoices from PDF files

"Book this invoice PDF into e-arveldaja and match it to the bank payment"

The assistant will extract invoice data from the PDF, reuse booking treatment from similar confirmed invoices by the same supplier when available, and otherwise fall back to purchase articles / local accounting rules before creating the invoice and matching it to bank transactions.

Batch-process a folder of invoices and receipts

"Process all the invoices in the arved/ folder and book them into e-arveldaja"

The assistant will scan the folder, OCR-parse each PDF/JPG/PNG, extract invoice data, resolve suppliers, and detect duplicates, then preview what can be auto-booked. The flow is staged, not one pass: creating and uploading PROJECT (draft) purchase invoices happens only after you approve the preview, and confirming those invoices and matching them to bank transactions are separate follow-up approvals. Purchase booking defaults come from confirmed supplier history first, then from accounting-rules.md if present. Dry run by default so you can review before committing. If invoice creation succeeds but a later step like document upload or confirmation fails, the tool now auto-invalidates the created purchase invoice and reports that file as failed instead of leaving a stray draft behind.

Book Lightyear investment trades and income

Download your Lightyear account statement CSV and capital gains report, then:

"Create e-arveldaja journal entries from these Lightyear CSVs"

The assistant will parse the trades, pair foreign currency conversions, calculate capital gains from the FIFO report, and create journal entries with the correct securities accounts. Dividends, fund distributions, and cash interest are also imported from the account statement CSV.

Import bank statements (CAMT.053)

Download your bank statement as a CAMT.053 XML file (supported by LHV, Swedbank, SEB, Coop, Luminor), then:

"Import bank transactions from my LHV statement XML into e-arveldaja"

The assistant will parse the ISO 20022 XML, create bank transactions with correct amounts and counterparties, detect duplicates by bank reference, and handle batched entries and mixed currencies. Dry run by default.

Import Wise bank transactions

Download the regular Wise transactions CSV from the Transactions view, then:

"Import my Wise transactions from transaction-history.csv into e-arveldaja"

The assistant will parse the CSV, create incoming and outgoing bank transactions from Wise's Direction field, and separate Wise fees into their own entries for proper expense accounting. Supports EUR and foreign currency card payments (USD etc.).

For now, this expects the normal transactions CSV export from Wise Transactions, not the special statement/report exports under Statements or Reports. Wise support is still lightly tested; if you hit an import issue, please open an issue or report it.

Generate financial reports

"Generate a P&L and balance sheet as of 28.02.2026"

Reconcile bank transactions

"Match unconfirmed bank transactions to invoices"

Inter-account transfer reconciliation is conservative: if multiple candidate matches have the same top confidence, it reports the transfer as ambiguous and skips confirmation instead of guessing.

Month-end close

"Run the month-end close checklist for February 2026"

Estonian tax: dividends and owner expenses

"Prepare a dividend package for 5000 EUR"

The assistant will compute the 22/78 corporate income tax, check retained earnings sufficiency and net assets against share capital (ÄS §157), and create the journal entry with correct postings.

"Reimburse my business expense of 45.50 EUR from Bolt"

For owner-paid expenses, the server now tries to give sensible defaults:

• ordinary VAT-registered business receipts default to full input-VAT deduction
• likely restricted or mixed-use categories such as passenger-car / fuel / representation-like costs ask for clarification instead of guessing
• if you have a stable internal policy, you can encode it in accounting-rules.md

Updating

How you update depends on how you set up the server:

Using npx

If your MCP config runs npx -y e-arveldaja-mcp, you usually just need to restart your AI assistant or reload the MCP server. On the next start, npx will fetch the latest published version.

If your client keeps using an older cached version, force-refresh it once:

npx -y e-arveldaja-mcp@latest

Then restart the MCP server in your client.

Running from a local git checkout

Pull the latest changes, reinstall dependencies if needed, rebuild, then restart your AI assistant:

git pull
npm install
npm run build

If your MCP config points to dist/index.js, the rebuild step is required after updating the source.

Development

Run the integration suite with:

npm run test:integration

This now runs self-contained MCP surface checks by default against a locally spawned server process with fake test credentials. The live API integration checks remain opt-in and require real credentials plus:

EARVELDAJA_INTEGRATION_TEST=true npm run test:integration

Releasing to the MCP Registry

Claude Cowork discovers public MCP servers through the MCP Registry. Pushing to GitHub is not enough: publish the same version to npm first, then publish this repo's server.json metadata to the registry.

Before publishing, make sure these versions all match:

• package.json version
• package-lock.json root package version
• server.json top-level version
• server.json packages[0].version

Also make sure package.json mcpName exactly matches server.json name; the registry uses that to verify npm package ownership.

Run the normal checks before publishing:

npm run validate:release
npm run build
npm test
npm run test:integration

Publish the npm package:

npm login
npm publish

Use the official mcp-publisher binary from the modelcontextprotocol/registry GitHub releases rather than third-party snap/brew packages. Unofficial channels can lag behind the current schema and reject the $schema version as "deprecated". A one-liner to install the latest official binary into ~/.local/bin (make sure that directory is on your PATH):

mkdir -p ~/.local/bin
curl -sSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" \
  | tar xz -C /tmp mcp-publisher
install -m 0755 /tmp/mcp-publisher ~/.local/bin/mcp-publisher
rm -f /tmp/mcp-publisher

Then authenticate and publish the registry entry:

npm run registry:login
npm run registry:publish

Verify the published entry:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.iseppo/e-arveldaja-mcp"

Good to know

• Dry run by default. Batch operations (bank import, Wise import, Lightyear booking, receipt processing, auto-confirm) preview results first. You must explicitly confirm before mutating records. Receipt batches use execution_mode="create" to create/upload unconfirmed PROJECT invoices; confirmation is a separate approval step.
• A plan handle is not approval. The mutating import/reconciliation workflows (CAMT, Wise, Lightyear, bank reconciliation, credential setup) return a one-attempt server plan handle that binds the exact reviewed scope. The handle is not consent to mutate — the assistant still needs your explicit approval, and if anything drifts between preview and execution the plan is rejected before any record is created.
• Source documents on every entry. Attach, download, or delete the source document (PDF/JPG/PNG) on any purchase invoice, sale invoice, manual journal, or bank transaction with attach_document / get_document / delete_document; find_missing_documents flags entries that lack one (Estonian RPS law requires a source document on every accounting entry).
• Accounting choices prefer evidence. For purchase booking, the server prefers treatment from similar confirmed supplier invoices. If that history is missing, it can use accounting-rules.md. For unmatched bank-transaction auto-booking, it no longer invents VAT treatment from weak heuristics alone.
• Large datasets need date filters. The server loads up to 200 pages of data per query. Companies with thousands of invoices or transactions should narrow reporting and reconciliation tools with date ranges — otherwise the tool will ask you to.
• Caching. API responses are cached for 2–5 minutes and reference data for up to 10 minutes. The server automatically invalidates caches when you create, update, or delete records through MCP tools. Changes made directly in the e-arveldaja web UI are not visible until the cache expires; call clear_cache or pass fresh: true to balance/reporting tools when you need the next read to fetch current upstream data.
• EUR by default. All amounts are EUR unless a different currency is specified.
• Multi-company. Place multiple apikey*.txt files and use list_connections / switch_connection. Switching clears the previous and target connections' cached data, so one company's records are never served to another.
• Node.js 18+ required.
• File access scope. By default, file-reading tools can access supported files under the working directory and /tmp. Set EARVELDAJA_ALLOWED_PATHS (colon-separated) to allow additional directories, or EARVELDAJA_ALLOW_HOME=true to allow the entire home directory.
• Human-editable local accounting rules. accounting-rules.md lets you store company-specific booking defaults and annual-report overrides in Markdown instead of code or JSON.
• Session audit log. Every mutating operation (create, update, delete, confirm, import) is logged to a human-readable Markdown file at logs/{connection}.audit.md in the working directory. Each entry includes timestamps, tool name, entity details, account postings, and financial amounts. Use get_session_log to view, list_audit_logs to browse all companies, and clear_session_log to reset. The log persists across sessions and is company-specific. Set EARVELDAJA_AUDIT_LANG=en for English labels (default: Estonian).
• Tag MCP-created invoices. Set EARVELDAJA_TAG_NOTES=true to append (e-arveldaja-mcp) to the notes field of all invoices created by the server. Off by default.
• Debug log file. Set EARVELDAJA_LOG_FILE=/path/to/mcp.err.log to tee everything the server writes to stderr (warnings, fatal errors, and — once the MCP transport is up — the structured logger output) into the given file in append mode. Off by default. Cross-platform (Linux, macOS, Windows). Useful when the MCP host swallows stderr; example: EARVELDAJA_LOG_FILE=/tmp/mcp.err.log.
• OCR text is sandboxed. Raw OCR output from PDFs and images (raw_text, receipt-line description) is wrapped in per-call nonce delimiters (<<UNTRUSTED_OCR_START:{nonce}>> / <<UNTRUSTED_OCR_END:{nonce}>>) before being returned to the LLM, so a scanned receipt cannot smuggle tool-call instructions into your agent's context.
• Cross-system file input. When the MCP server runs on a different host from your client (e.g. Claude desktop, Cowork, Cursor, or a remote container), file-reading tools also accept a file_path of the form base64:<b64data> (for PDF / PNG / JPEG / CAMT XML) or base64:<ext>:<b64data> (e.g. base64:csv:QSxCLEMK...) so files on the client side no longer need to exist on the server's filesystem.

Non-goals (handled natively by e-arveldaja)

A few things are deliberately out of scope, because e-arveldaja already does them and duplicating them in the MCP layer would risk double-booking:

• No VAT/KMD return (käibedeklaratsioon). e-arveldaja generates the KMD natively from the confirmed ledger and files it to EMTA. The server's tax-rules layer (earveldaja://tax_rules) is advisory only — it informs booking decisions, it does not produce or file returns.
• No EMTA prepayment-account tax entries. A bank transfer to EMTA (Maksu- ja Tolliamet) is booked as a prepayment-account top-up (Debit ettemaksukonto / Credit bank); the tax-expense entries that draw it down are created by e-arveldaja from its EMTA prepayment-account statement, not by this server.
• update_transaction is metadata-scoped. It edits only transaction metadata (bank reference and description fields); it never changes amounts, postings, or distributions. Use the reconcile/booking tools for those.

Privacy

Document parsing (PDF, JPG, PNG) uses LiteParse OCR locally by default. If you set EARVELDAJA_LITEPARSE_OCR_SERVER_URL, the server will send documents to that configured OCR endpoint instead of staying fully local for OCR. Remote OCR endpoints must use https; plain http is only accepted for localhost / loopback OCR services. By default, the server may also read supported document files under the working directory and /tmp; set EARVELDAJA_ALLOW_HOME=true to also include your whole home directory, or EARVELDAJA_ALLOWED_PATHS (colon-separated) for an explicit allowlist. In all cases, the extracted text is returned to your AI assistant via the MCP protocol, so it will be processed by whichever LLM you are using (Claude, Codex, Gemini, etc.). The server's own outbound connections are therefore limited to the e-arveldaja API (rmp-api.rik.ee), optionally the Estonian Business Registry (ariregister.rik.ee) for supplier lookups, and optionally your configured OCR server.

Feedback and Bug Reports

Feature requests, bug reports, and invoices that don't parse correctly are welcome on the GitHub Issues page.

If you'd rather not upload your invoice publicly, email it directly to indrek.seppo@gmail.com.

License

Apache License 2.0