personal-finance-mcp

Inoffiziell. Dieses Projekt ist nicht mit Plaid Inc. verbunden, wird von Plaid Inc. nicht unterstützt und nicht gesponsert. „Plaid“ ist eine Marke von Plaid Inc. Dies ist ein selbst gehosteter Client, der über die von Ihnen bereitgestellten Anmeldedaten mit der API von Plaid kommuniziert.

Ein selbst gehosteter, schreibgeschützter MCP-Server, der Ihre Banken, Kreditkarten, Kredite und Brokerage-Konten (über Plaid) mit einem MCP-Client wie Claude Code verbindet. Stellen Sie Fragen zu Ihren eigenen Finanzen in einfachem Englisch – ohne Drittanbieter-Aggregator (Monarch, Mint usw.).

Was Sie fragen können

• „Wie hoch ist mein Gesamtsaldo über alle Konten hinweg?“

• „Zeige mir Transaktionen über 100 $ in den letzten 30 Tagen.“

• „Für welche Abonnements zahle ich noch?“

• „Wie viel habe ich letzten Monat für Lebensmittel ausgegeben?“

• „Muss eine Bank erneut authentifiziert werden?“

Beispielsitzung (illustrativ):

you    : What did I spend on groceries last month?
claude : [calls get_transactions]
         $487.23 across 14 transactions. Top merchants:
         Whole Foods ($198), Trader Joe's ($156), Safeway ($89).

you    : Any subscriptions I'm still paying for?
claude : [calls get_recurring_transactions]
         7 active recurring outflows totaling $142/mo:
         Netflix ($15.99), Spotify ($11.99), NYT ($4), ...

Tools

Alle 9 Tools sind schreibgeschützt. Jedes gibt {<data>: [...], "warnings": [...]} zurück, sodass eine defekte Bankverbindung nicht die gesamte Abfrage unterbricht.

Schnellstart

Erfordert Python 3.11+, ein Plaid-Konto (kostenloser Testplan) und einen MCP-Client.

1. Plaid-Einrichtung

1. Registrieren Sie sich unter https://dashboard.plaid.com/signup → wählen Sie den Trial-Plan (kostenlos, 10 Elemente).

2. Team Settings → Products: aktivieren Sie Transactions, Liabilities, Investments.

3. Team Settings → API: kopieren Sie Ihre client_id und das Produktions-secret.

2. Installation

git clone https://github.com/<you>/personal-finance-mcp.git
cd personal-finance-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then fill in PLAID_CLIENT_ID and PLAID_SECRET
pytest -v              # sanity check

3. Jede Bank verknüpfen

Führen Sie dies einmal pro Bank aus, die Sie verbinden möchten:

uvicorn link_helper:app --port 8765

Öffnen Sie http://localhost:8765, klicken Sie auf Link a bank und schließen Sie Plaid Link ab. Das Terminal gibt eine Zeile wie PLAID_TOKEN_CHASE=access-prod-xxx... aus – fügen Sie diese in .env ein und wiederholen Sie den Vorgang für jede Bank.

4. Ausführen

python server.py   # serves on http://localhost:8000/mcp

5. Zu Claude Code hinzufügen

claude mcp add --transport http personal-finance http://localhost:8000/mcp

Versuchen Sie „list my accounts“, um dies zu bestätigen.

Bereitstellung

Für eine Bereitstellung, die Sie von überall nutzen können:

• Docker (enthalten): docker build -t personal-finance-mcp . && docker run --rm -p 8000:8000 --env-file .env personal-finance-mcp

• Jeder Python-Host (Fly.io, Railway, Raspberry Pi + Tailscale, ein VPS): Setzen Sie die Umgebungsvariablen aus .env.example, machen Sie /mcp über HTTPS verfügbar und sichern Sie es mit einer Authentifizierung.

• Prefect Horizon (was der Autor verwendet – 0 $ laufende Kosten): siehe docs/DEPLOYMENT.md für die vollständige Anleitung.

Sichern Sie den Endpunkt. Ein exponierter MCP-Endpunkt mit Ihren Token legt jedes verknüpfte Konto offen. Verwenden Sie OAuth 2.1, Cloudflare Access oder binden Sie ihn nur an ein privates Netzwerk.

Sicherheit

• Single-Tenant. Eine Bereitstellung pro Person. Nicht teilen.

• Schreibgeschützt. Kein Tool ändert den Status bei irgendeinem Institut. Fügen Sie keine Tools hinzu, die dies tun.

• Token leben in Umgebungsvariablen, niemals auf der Festplatte. .env wird von git ignoriert.

• Sie sind für die Plaid-Compliance verantwortlich. Sie sind der Plaid-Kunde unter Ihrem eigenen Konto.

Vor jeder Bereitstellung:

• [ ] .env niemals committen: git log --all -- .env gibt nichts zurück

• [ ] Keine echten Token in der Historie: git log -S'access-prod-' --all gibt nur Platzhalter zurück

• [ ] Authentifizierungsschutz vor dem MCP-Endpunkt (oder nur localhost)

• [ ] HORIZON=1 (oder ähnlich) in der Bereitstellungsumgebung gesetzt, blockiert link_helper.py dort

• [ ] Überprüfen Sie get_institutions_status() alle paar Wochen auf Anforderungen zur erneuten Authentifizierung

Fehlerbehebung

Tool gibt trotz vorhandener Daten nichts zurück. Plaid-Produkte waren nicht aktiviert, als Sie die Bank verknüpft haben. Verknüpfen Sie sie erneut mit aktiven Transaktionen + Verbindlichkeiten + Investitionen. Das Tool zeigt PRODUCTS_NOT_SUPPORTED in warnings an, wenn dies die Ursache ist.

get_institutions_status() zeigt re_auth_required. Die Plaid-Sitzung der Bank ist abgelaufen. Führen Sie link_helper.py im Update-Modus aus – Ihr bestehendes Zugriffstoken bleibt gleich. Siehe docs/DEPLOYMENT.md.

Plaid Link zeigt eine Bank als „nicht unterstützt“ an (häufig bei Amex). Normalerweise ein INSTITUTION_REGISTRATION_REQUIRED-Problem – OAuth-Banken benötigen zuerst eine Registrierung pro Institut im Plaid-Dashboard. Siehe docs/TROUBLESHOOTING.md.

Weitere Probleme: docs/TROUBLESHOOTING.md.

Architektur

• server.py — FastMCP-Server, 9 schreibgeschützte Tools.

• plaid_client.py — Plaid SDK-Wrapper: SecretStr-Token-Schwärzung, 5-Minuten-Gesundheitscache pro Element, Antwortformatierung, strukturierte Fehlerzuordnung.

• link_helper.py — Nur lokal nutzbare FastAPI-App für Plaid Link. Verweigert den Dienst, wenn HORIZON=1 gesetzt ist.

Tieferer Einblick (einschließlich warum /transactions/get gegenüber /transactions/sync): docs/ARCHITECTURE.md.

Mitwirken

Siehe CONTRIBUTING.md. Der Umfang ist bewusst eng gefasst: schreibgeschützt, Single-Tenant, Plaid-basiert.