E Arveldaja Mcp

e-arveldaja MCP Server

[npm]

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

Limited VAT taxpayers, KMD row 7 and plan-bound dividends (0.40.0, behaviour change). The server now tells a limited VAT registration (piiratud maksukohustuslane, KMS § 21) from a full one via EMTA's public VAT-number query, never deducts input VAT for a limited or unknown status, and limited_vat books the monthly self-assessed VAT (D cost / C 2511) after approval and gives the KMD rows. Reverse-charge purchases from non-EU suppliers now use the KMD row 7 option (RIK-confirmed); an EU VAT number on the invoice or supplier keeps row 6. prepare_dividend_package now starts from the approved annual report figures you supply, and dividend and year-end close execution require the preview's plan_handle. See the CHANGELOG for details.

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 [email protected].

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

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 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. Opening balances (algbilanss)

Opening balances come directly from e-arveldaja as operation_type=INITIAL. Account balances, statements, annual reports and dividend checks include registered, non-deleted opening postings with their original dates, clients and dimensions. If no INITIAL exists, calculations use the remaining API journals normally. Annual cash flow excludes the opening position.

The former import_opening_balances tool and local opening-register support have been removed. Existing local opening-balances.json files are left untouched and are no longer read. Manage opening balances in e-arveldaja.

Trimming the tool surface

Choose one explicit surface with EARVELDAJA_PROFILE: guided is the opt-in 19-tool daily-bookkeeping surface; guided-sales adds the manage_sale_invoice sales façade (20 tools) — reads invoices and runs the full sale-invoice lifecycle (create/update/delete/confirm/invalidate/send/recurring, plus inline resolve-or-create customer) behind the two-call prepare/execute approval gate; standard is the absent-variable compatibility default (128 tools); and full exposes all 148 tools, including granular and configured-mode credential administration. Every non-guided surface also carries get_server_status, a compact read-only report of the running version, active profile, and any active point-of-use release notices.

The setup choices map exactly: Daily bookkeeping → guided; Daily bookkeeping plus sales invoices → guided-sales; Bookkeeping plus investments → standard with Lightyear enabled; Full advanced toolset → full. Guided profiles are opt-in in this release, not the recommended/default daily surface. After changing profiles, restart and run fresh previews; an old proposal or plan handle is never approval under the new profile.

Existing exposure flags remain compatible. If any legacy exposure flag is explicitly present, the effective profile is custom and those flags keep their existing independent behavior. A reviewed credential import that explicitly selects a named profile removes those legacy exposure keys from the same selected local/global .env, so restart resolves to the chosen profile rather than custom; the preview lists the exact keys to be removed. Profile and credentials use the same .env; there is no second config format.

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, limited_vat) 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 custom deployment with every disable flag set (incl. Lightyear) has 85 tools instead of the standard 128. Conversely, EARVELDAJA_PROFILE=full exposes the complete 148-tool catalog.

EARVELDAJA_DOCUMENT_READING=1 (opt-in, off by default) lets your assistant read a single invoice itself: process_accounting_document gains mode='read' and mode='verify', every value is checked against the printed text, and only the questions the server cannot settle are put to you before the draft is created. It adds no tool, so the tool counts above do not change.

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.gitcd e-arveldaja-mcpnpm 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. A sell debits the broker account with the cash the statement shows, credits the investment at Lightyear's FIFO cost basis, and books the gain or loss as the difference. Dividends, fund distributions, and cash interest are also imported from the account statement CSV, each to its own income account (8330, 8320 and 8400 by default).

To check a year of existing Lightyear bookings against what the tools would book now, run the read-only comparison script from the project directory:

npm run lightyear:rebuild-compare -- --statement AccountStatement-LY-<ACCOUNT>-2026-01-01_2026-10-30_en.csv \  --gains CapitalGainsStatement-2026.csv --from 2026-01-01 --to 2026-10-30 \  --opening-as-of 2025-12-31 --start-usd-holding 0.37 --broker-dimension <id> --out lightyear-2026.md

It never writes: its API client refuses anything but GET, and it touches no pool store, plan or audit log (--no-books skips the API entirely). The report lists the proposed journals, the USD pool per month end, realised FX per month and the differences to your books per account, month and LY: reference. Replacing journals is a separate decision.

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"

For a month that is still open, overdue invoices are evaluated as of today (Estonian date); invoices still payable by month-end are listed separately under due_before_month_end_*.

Year-end close

"Prepare the 2025 year-end close"

The assistant proposes RIK's two closing entries (31 Dec result to 2970, 1 Jan transfer to retained earnings 2960, optionally part to reserve capital), shows what already exists, and books only what is missing after your approval. The fiscal year is the calendar year.

Estonian tax: dividends and owner expenses

"Prepare a dividend package for 5000 EUR"

The assistant asks for the two figures of your last approved annual report (retained earnings and profit for the year), checks them against the books, subtracts what has been distributed since, computes the 22/78 corporate income tax, checks net assets against share capital and reserves (ÄS §157), and creates 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 pullnpm installnpm 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 full checks on the release commit before tagging it (metadata, build, unit and integration tests, packed-package smoke test):

npm run release:check

Publish the npm package. prepublishOnly reruns only the fast package checks (metadata, build, packed smoke test, about 30 s), so a one-time password from --otp is still valid when the upload starts; the full test suite runs in release:check and in CI.

npm loginnpm publish --otp=<code>

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/bincurl -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-publisherinstall -m 0755 /tmp/mcp-publisher ~/.local/bin/mcp-publisherrm -f /tmp/mcp-publisher

Then authenticate and publish the registry entry:

npm run registry:loginnpm 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.
• Third-party payers. e-arveldaja books a bank receipt under the transaction's client (the payer), so when someone else pays an invoice the receivable credit would land in the wrong client sub-ledger. confirm_transaction refuses such a confirm (linked_invoice_client_mismatch) unless you pass reassign_client_to_invoice: true, checks the resulting registration journal after every invoice-linked confirm, and reconcile_bank_transactions lists these cases as third_party_payer_reviews instead of auto-confirming them. run_accounting_report with report: "receipt_client_alignment" audits existing books.
• 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. The active connection is per server process: if your MCP host restarts the server, it comes back on EARVELDAJA_DEFAULT_CONNECTION (index or name; default index 0, unknown values fail startup). With several connections configured, every non-readonly tool accepts an optional connection argument (index or name); a call whose value is not the active connection is refused with connection_mismatch before any API request, so you can pin the target company on each write instead of relying on an earlier switch_connection.
• Node.js 18+ required.
• File access scope. By default, file-reading tools can access supported files under the working directory and the OS temp directory (os.tmpdir(): $TMPDIR, usually /tmp). EARVELDAJA_ALLOW_HOME=true adds the entire home directory. EARVELDAJA_ALLOWED_PATHS (colon-separated; semicolon on Windows) replaces these defaults with exactly the listed directories — list the working directory too if you still need it; EARVELDAJA_ALLOW_HOME is ignored while it is set.
• 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 the OS temp directory; set EARVELDAJA_ALLOW_HOME=true to also include your whole home directory, or EARVELDAJA_ALLOWED_PATHS (colon-separated) for an explicit allowlist that replaces the defaults. 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, optionally the European Central Bank data API (data-api.ecb.europa.eu, public reference rates, no credentials) during Lightyear dry runs that value USD at the ECB rate (fx_source: "ecb" distributions, buys funded from the USD cash fund, book_lightyear_fx_revaluation previews — never at execute, which replays the rates the reviewed plan froze), 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 [email protected].

License

Apache License 2.0