# kontozack-mcp

MCP server that parses **German bank statement PDFs** into structured, validated
transaction data — right inside Claude Desktop, Claude Code, Cursor, or any other
[Model Context Protocol](https://modelcontextprotocol.io) client.

Built by [kontozack.de](https://kontozack.de), the German bank-statement converter.

> **Honest scope note:** this server currently supports **SumUp account statements**
> ("SumUp Account Kontoauszug"). More German bank formats are coming. Need another
> format today? The web version at [kontozack.de](https://kontozack.de) supports more.

## What it does

| Tool | Purpose |
| --- | --- |
| `parse_bank_statement` | Parse a statement PDF into header data (IBAN, period, balances) + structured transactions. Above 500 transactions the list is truncated (with `total_count`) — use the CSV export for everything. |
| `export_bank_statement_csv` | Write **all** transactions to a German-style CSV: semicolon separator, comma decimals, UTF-8 BOM (opens cleanly in German Excel, suitable as a DATEV import basis). |
| `validate_bank_statement` | Run only the proof-calculation checks: parsed sums must match the statement's own header totals, and every row must carry a running balance. |

Every parse is **validated by proof calculation** — the sums of all extracted
transactions must add up exactly to the totals printed on the statement itself
(incoming, outgoing incl. fees, opening/closing balance delta). If a check fails,
the tools tell you.

All processing happens **locally on your machine**. Your bank data never leaves
your computer.

## Requirements

- Node.js 18 or newer

## Installation & configuration

### Claude Desktop

Add to your `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kontozack": {
      "command": "npx",
      "args": ["-y", "kontozack-mcp"]
    }
  }
}
```

Restart Claude Desktop afterwards.

### Claude Code

```bash
claude mcp add kontozack -- npx -y kontozack-mcp
```

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "kontozack": {
      "command": "npx",
      "args": ["-y", "kontozack-mcp"]
    }
  }
}
```

## Usage examples

Ask your AI assistant things like:

- *"Parse the bank statement at /Users/me/Downloads/sumup-2025.pdf and summarize the biggest expenses."*
- *"Convert /Users/me/Downloads/sumup-2025.pdf to CSV at /Users/me/Desktop/buchungen.csv."*
- *"Validate whether /Users/me/Downloads/sumup-2025.pdf was read completely."*

File paths must be **absolute**. The server reads the PDF locally and never
uploads it anywhere.

## Development

```bash
npm install
npm run build       # compile TypeScript to dist/
npm run typecheck   # tsc --noEmit
npm test            # build + integration tests (needs a local test PDF, see tests/run-tests.mjs)
```

---

## Deutsch: Kontoauszüge für KI-Agenten

`kontozack-mcp` macht deutsche **Kontoauszug-PDFs** für KI-Assistenten lesbar —
als [MCP](https://modelcontextprotocol.io)-Server für Claude Desktop, Claude Code,
Cursor & Co.

- **`parse_bank_statement`** – liest den Auszug (aktuell: **SumUp-Kontoauszüge**)
  und liefert Kopfdaten (IBAN, Zeitraum, Salden) plus strukturierte Buchungen.
- **`export_bank_statement_csv`** – exportiert alle Buchungen als deutsches CSV
  (Semikolon, Komma-Dezimaltrennzeichen, UTF-8-BOM — öffnet sauber in Excel,
  geeignet als Basis für den DATEV-Import).
- **`validate_bank_statement`** – Beweisrechnung: Die Summen aller ausgelesenen
  Buchungen müssen exakt auf die im Auszug gedruckten Summen aufgehen.

Die Verarbeitung läuft **komplett lokal** — Ihre Bankdaten verlassen den Rechner
nicht. Weitere Formate und die Web-Version: **[kontozack.de](https://kontozack.de)**.

## License

MIT — see [LICENSE](LICENSE).