Finance Manager MCP

Selbst gehostete persönliche Finanzverwaltung für MCP-Clients. Deine Banken bleiben schreibgeschützt (SimpleFIN), deine Daten liegen in einer lokalen SQLite-Datei, die dir gehört, und ein LLM kann nur deterministische Summen abfragen — es schreibt nie in das Hauptbuch.

SimpleFIN (read-only)
    → raw_syncs (append-only JSON)
    → truth tables (accounts, transactions, rules, budgets)
    → warm-cache aggregates
    → atomic functions / MCP tools (stdio + gRPC)

Warum diese Architektur

• Idempotente Erfassung — Transaktionen werden über die bankseitig vergebene SimpleFIN-ID identifiziert. Eine erneute Synchronisierung desselben Dumps ergibt netto null neue Zeilen; identisch aussehende neue Buchungen werden nie zusammengefasst.

• Deterministische Kategorisierung — Regex-Regeln mit dem Prinzip „erster Treffer gewinnt“. Kein Modell im Schreibpfad.

• Warmer Cache — monatliche Ausgaben, Cashflow, Nettovermögens-Snapshots und wiederkehrende Zahlungsströme werden in SQLite gespeichert, sodass Neustarts sofort warm starten. Der Cache wird abgeleitet; rebuild-cache regeneriert ihn aus den Basistabellen.

• Profile-UUID-Namensräume — jedes Schreibwerkzeug erfordert eine profile_id. Mehrere Profile vermischen sich nie.

• Dualer Transport — stdio für Claude Deskursive / Cursor, gRPC über das Schwesterpaket GRPC-MCP.

Related MCP server: personal-finance-mcp

Einrichtung

Python 3.11+.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix:    source .venv/bin/activate
pip install -e ".[dev]"
# optional gRPC transport (sibling ../GRPC-MCP)
pip install -e "../GRPC-MCP/python"
pip install -e ".[grpc]"

cp .env.example .env
# paste a Fernet key into FINANCE_ENCRYPTION_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

finance-mcp init                          # creates data/finance.db + a default profile
finance-mcp profile list                  # copy the profile UUID

Mit SimpleFIN verbinden

Über einen MCP-Client wird eine Bank verbunden. Der Agent sollte:

1. begin_simplefin_connect aufrufen (oder den Prompt connect_simplefin verwenden).

2. Dir bridge.simplefin.org anzeigen — du meldest dich an, Verbindung zur Banken (read-only) herzustellen und kopierst das einmalige Setup-Token.

3. claim_connection mit diesem Token aufrufen. Die Zugriffs-URL ist im Ruhezustand verschlüsselt.

4. Optional sync_now mit derselben profile_id aufrufen.

Die CLI funktioniert weiterhin, wenn du ein Terminal bevorzugst:

finance-mcp claim-token --token "<setup-token>" --name "My Banks" --profile <PROFILE_UUID>
finance-mcp sync --profile <PROFILE_UUID>

sync kann gefahrlos über den Task Scheduler / cron ausgeführt werden. Überlappende Zeitfenster führen nicht dazu, dass doppelt gezählt wird.

Server starten

finance-mcp serve-stdio                   # Claude Desktop / Cursor
finance-mcp serve-grpc --auth bearer      # sibling GRPC-MCP transport
finance-mcp token new --name cursor --profile <PROFILE_UUID>

Das Bearer-Token wird nur einmal ausgegeben. gRPC speichert nur den SHA-256-Hash.

Atomare Funktionen

Alles in finance_mcp.api ist eine gewöhnliche Funktion. MCP-Tools sind dünne Wrapper. Importiere die Bibliothek, ohne einen Server zu starten:

from finance_mcp.config import Settings
from finance_mcp.core.db import Database
from finance_mcp import api

db = Database.from_settings(Settings.from_env())
print(api.net_worth(db, profile_id))

Lesen

list_accounts, get_balances, net_worth, net_worth_history, search_transactions, recent_transactions, spending_by_category, cash_flow, recurring_streams, upcoming_payments, budget_status, list_rules, sync_status, profile_info, list_profiles, begin_simplefin_connect

Schreiben (erfordert immer profile_id)

claim_connection, create_rule, update_rule, delete_rule, apply_rules, create_budget, update_budget, delete_budget, sync_now

Tests

Die Testsuite ist hermetisch — nur synthetische Fixtures, keine Zugangsdaten.

pytest -q

Sicherheit

• SimpleFIN-Zugriffs-URLs werden mit FINANCE_ENCRYPTION_KEY (Fernet) verschlüsselt. Lege eine Sicherung des Schlüssels an.

• gRPC-Bearer-Tokens werden als Hashes gespeichert.

• Lesewerkzeuge öffnen SQLite mit mode=ro. Schreibwerkzeuge sind der einzige Mutationspfad und auf Profile begrenzt.

• data/ und .env werden von Git ignoriert.

Lizenz

Verwende es nach Belieben für deine persönliche, selbst gehostete Finanzverwaltung.