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. 133 tools, 15 workflow prompts, 13 resources. Works with any MCP client — Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, and others.

> **Safer CAMT re-imports.** `import_camt053` preserves CAMT bank-reference and counterparty-account metadata in the writable transaction description when the e-arveldaja API drops the dedicated fields. Long bank references are stored as stable hashes, marker-only prior imports still surface in duplicate review when the exact key does not match, and repeated CAMT imports are less likely to create duplicate PROJECT rows. 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` remain available as compatibility primitives. 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 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.

### 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). If you already keep rules next to the project (an `accounting-rules/` folder or a legacy `accounting-rules.md`), that location is used as-is; on a fresh install the bundle defaults to your per-user config directory (`~/.config/e-arveldaja-mcp/accounting-rules`, or the platform equivalent) — the same place credentials live — so it survives reinstalls and is shared across MCP clients. Two environment variables override the location:

- `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.

### 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. The Lightyear investment tools are an optional feature group:

- `EARVELDAJA_DISABLE_LIGHTYEAR=1` — drops the Lightyear investment tools (`book_lightyear_*`, `parse_lightyear_*`, `lightyear_portfolio_summary`). Use it when the company does not track investments.

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

<details>
<summary>Alternative: environment variables</summary>

```bash
export EARVELDAJA_API_KEY_ID=...
export EARVELDAJA_API_PUBLIC_VALUE=...
export EARVELDAJA_API_PASSWORD=...
```

</details>

<details>
<summary>Building from source</summary>

```bash
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
```

</details>

## Workflows (MCP Prompts)

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

| Prompt | Description |
|---|---|
| `accounting-inbox` | Start here: scan a workspace, detect likely inputs, suggest the next safe dry-run steps, and ask only the smallest necessary follow-up questions |
| `resolve-accounting-review` | Turn one accounting review item into a concrete next-step plan with compliance references |
| `prepare-accounting-review-action` | Prepare the concrete next action for a resolved review item (delete duplicate, save rule, etc.) |
| `book-invoice` | Book a purchase invoice from PDF: extract, validate, resolve supplier, preview, create, upload, confirm |
| `receipt-batch` | Scan receipts and create/upload PROJECT purchase invoices through `receipt_batch`, then optionally confirm after separate approval |
| `import-camt` | Parse CAMT.053 XML, preview imported bank transactions through `process_camt053`, then create after approval |
| `import-wise` | Preview Wise CSV import results, fees, duplicates, and Jar skips before execution |
| `classify-unmatched` | Group unmatched bank transactions, preview suggested booking actions, then apply after approval |
| `reconcile-bank` | Match bank transactions through `reconcile_bank_transactions`, then auto-confirm or review manually |
| `month-end-close` | Blockers, missing docs, duplicates, trial balance, P&L, balance sheet |
| `new-supplier` | Create supplier with Estonian business registry lookup |
| `company-overview