tuskledger-mcp

Model Context Protocol-Server für Tusk Ledger. Gibt Ihrem KI-Assistenten typisierten Zugriff auf Ihre lokalen persönlichen Finanzdaten — ohne dass etwas Ihren Rechner verlässt.

Was ist das?

Ein kleines Python-Paket, das als lokaler Model Context Protocol-Server auf Ihrem Laptop läuft. Sobald Sie es zur Konfiguration Ihres KI-Clients hinzugefügt haben (Claude Desktop, Cursor, Cowork, Claude Code, alles, was MCP unterstützt), kann Ihr Assistent Tools aufrufen wie:

• list_accounts — jedes verbundene Konto mit Saldo + Synchronisierungsstatus

• query_transactions — Filtern nach Datum, Konto, Kategorie usw.

• search_transactions — Fuzzy-Textsuche über Händler und Notizen hinweg

• get_spending_summary — Summen nach Kategorie für einen Datumsbereich

• get_top_merchants — wem Sie am meisten zahlen

• get_recurring_subscriptions — Netflix, Fitnessstudio usw.

• get_upcoming_bills — nächste 30 Tage mit laufendem Saldo

• get_net_worth — aktueller Stand + 12-Monats-Trend

• get_holdings — jede Investmentposition

• get_investments_summary — Portfolio-Zusammenfassung + Vermögensallokation

• get_retirement_projection — Monte-Carlo-Zusammenfassung für Ihr gespeichertes Szenario

• run_sync — Plaid-Abruf auslösen

• list_stale_accounts — Konten mit veralteten Daten

Der Server kommuniziert mit Ihrem lokalen Tusk Ledger-Backend unter http://127.0.0.1:8000. Keine Daten gelangen ins Internet. Die „MCP-Cloud“ existiert nicht — das Ganze ist ein einziger Python-Prozess, der auf Ihrem Rechner läuft und mit einem anderen Python-Prozess auf demselben Rechner kommuniziert.

Warum gibt es das?

Tusk Ledger ist für den agentengestützten Benutzer konzipiert — jemanden, der Claude / Cursor / Cowork bitten kann, Dinge zu tun, die vor fünf Jahren allein nicht möglich waren. Der MCP-Server ist der wirkungsvollste Schritt in Richtung dieses Ziels: Ihr Assistent erhält typisierten, strukturierten Zugriff auf Ihre Finanzdaten, anstatt die React-Benutzeroberfläche scrapen oder das Datenbankschema erraten zu müssen.

Praxisbeispiele nach der Installation:

• „Kategorisiere die Transaktionen der letzten 6 Monate von Whole Foods als Lebensmittel statt als Shopping.“ → Der Assistent fragt sie ab, Sie bestätigen, dann wird eine Regel erstellt.

• „Was habe ich im letzten Quartal für Kaffee ausgegeben?“ → 3 Sekunden, keine Klicks in der Benutzeroberfläche.

• „Mein Nettovermögen ist heute Morgen gesunken — woran liegt das?“ → Der Assistent ruft Konten, Salden und aktuelle Transaktionen ab und stellt eine Diagnose.

• „Bin ich auf dem richtigen Weg, mein HSA dieses Jahr voll auszuschöpfen?“ → Liest HSA-Topf + Beiträge seit Jahresbeginn + IRS-Limit, gibt die Differenz zurück.

Voraussetzungen

• Eine laufende Tusk Ledger-Installation (die Haupt-App)

• Python 3.10+

• Ein MCP-fähiger Client (Claude Desktop, Cursor, Cowork, Claude Code, …)

Installation

Option A — uvx (empfohlen; keine dauerhafte Installation)

Wenn Sie uv haben (pip install uv):

// In your MCP client's config
{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
    }
  }
}

uvx verwaltet die isolierte Python-Umgebung; nichts verschmutzt Ihr globales Python. Der Server wird beim ersten Aufruf abgerufen und zwischengespeichert.

Option B — pip install von GitHub

pip install git+https://github.com/BradMorphsters/tuskledger-mcp

Verweisen Sie dann Ihren MCP-Client auf das installierte tuskledger-mcp-Binary:

{
  "mcpServers": {
    "tuskledger": {
      "command": "tuskledger-mcp"
    }
  }
}

(Verwenden Sie den vollständigen Pfad von which tuskledger-mcp, falls Sie ein venv verwenden.)

Option C — Klonen für die Entwicklung

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Wo befinden sich die MCP-Client-Konfigurationen?

Starten Sie den Client nach dem Bearbeiten der Konfiguration neu. Der Server startet, wenn der Client startet, und wird beendet, wenn er geschlossen wird.

Konfiguration

Zwei Umgebungsvariablen, beide optional:

Beispiel:

{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
      "env": {
        "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
        "TUSKLEDGER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Authentifizierung

Diese v0 geht davon aus, dass Ihr Tusk Ledger-Backend mit DEV_BYPASS_AUTH=true läuft (das übliche Ein-Rechner-Muster, das in der README des Haupt-Repositorys dokumentiert ist). Wenn Sie die Authentifizierung aktiviert gelassen haben, schlagen die Aufrufe des MCP-Servers mit 401-Fehlern fehl, und Sie sehen den Fehler in der Antwort Ihres Assistenten.

Unterstützung für Authentifizierung steht auf der Roadmap. Bis dahin: Wenn Sie sowohl Authentifizierung als auch MCP nutzen möchten, führen Sie das Backend nur dann mit DEV_BYPASS_AUTH=true aus, wenn Sie den Assistenten verwenden, und schalten Sie es wieder um, wenn Sie fertig sind.

Was dieser Server absichtlich NICHT tut

Designbedingt ist v0 hauptsächlich lesend. Der Server bietet keine Funktionen für:

• Löschen von Konten, Transaktionen, Regeln oder Zielen

• Ändern des Datenbankschemas oder Ausführen von Migrationen

• Deaktivieren der Authentifizierung oder Rotieren des Verschlüsselungsschlüssels

• Berühren von Plaid-Zugriffstokens

• Senden von Daten irgendwohin außerhalb von 127.0.0.1

Die Begründung: Ein KI-Assistent sollte Ihnen helfen können, Ihre Daten zu verstehen und sichere Operationen (Synchronisierung, Abfragen) durchzuführen, aber irreversible Änderungen gehören in die Web-Benutzeroberfläche, wo Sie sehen können, was passieren wird. Wir werden möglicherweise in späteren Versionen strukturierte Schreib-Tools (z. B. „eine Regel erstellen“) mit expliziten Bestätigungsabläufen hinzufügen, aber die Hürde bleibt hoch.

Fehlerbehebung

Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — Ihre Tusk Ledger-App läuft nicht. Aus dem Haupt-Repository: ./start.sh.

401 Unauthorized bei einem Tool — Authentifizierung ist aktiv. Siehe Abschnitt „Authentifizierung“ oben. Führen Sie es vorerst mit DEV_BYPASS_AUTH=true aus.

404 Not Found — Das Backend hat den Endpunkt nicht, den wir aufrufen wollen. Wahrscheinlich bedeutet das, dass Sie eine ältere Version von Tusk Ledger verwenden. Aktualisieren Sie die Haupt-App, starten Sie Ihren MCP-Client neu.

Tools erscheinen nicht in Ihrem Assistenten — Der MCP-Server konnte nicht starten. Überprüfen Sie die MCP-Server-Protokolle Ihres Clients (Claude Desktop hat einen Menüpunkt „View MCP server logs“). Häufige Ursachen: falscher Pfad in der Konfiguration, Python nicht im PATH, uvx nicht installiert.

Allgemeiner Gesundheitscheck — Aus dem Haupt-Tusk Ledger-Repository: ./tuskledger doctor. Dies ist die kanonische Diagnose für die gesamte Installation.

Entwicklung

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -v

Die Tests starten keinen MCP-Transport — sie führen die Dispatch-Ebene direkt mit einem Mock-Client aus. Das MCP-Protokoll selbst ist nur ein Wrapper.

CI führt dieselbe Suite auf Python 3.10/3.11/3.12 über GitHub Actions aus (siehe .github/workflows/ci.yml).

Projekt-Links

• Haupt-App: https://github.com/BradMorphsters/tuskledger

• Projekt-Seite: https://www.tuskledger.com

• Für Agenten, die extern browsen: https://www.tuskledger.com/llms.txt

• Probleme / Diskussionen: https://github.com/BradMorphsters/tuskledger-mcp/issues

• Lizenz: MIT