Money Lover MCP Server

Node.js-Implementierung eines Model Context Protocol (MCP)-Servers, der die inoffizielle Money Lover REST-API kapselt. Der Server stellt 27 MCP-Tools für Authentifizierung, Geldbörsen, Kategorien, Transaktionen, Ereignisse, Schulden und statische Konfiguration bereit – dies ermöglicht KI-Assistenten oder MCP-kompatiblen Clients das Abfragen und Verwalten von persönlichen Finanzdaten.

Funktionen

• Automatische Authentifizierung über EMAIL/PASSWORD-Umgebungsvariablen – für die meisten Tools ist keine Token-Übergabe erforderlich.

• 23 Lese-Tools für Benutzerinformationen, Geldbörsen, Kategorien, Transaktionen, Ereignisse, Schulden, Symbole, Anbieter und statische Konfiguration.

• 4 Schreib-Tools: Erstellen, Aktualisieren und Löschen von Transaktionen, Geldbörsen und Kategorien.

• Große Antworten werden automatisch gekürzt, um den LLM-Kontext überschaubar zu halten (konfigurierbar über den limit-Parameter).

• Stdio-basierter Server, kompatibel mit Claude Code, Claude Desktop, Cursor und jedem MCP-Host.

• Token-Caching pro E-Mail unter ~/.moneylover-mcp/ mit automatischer Aktualisierung bei Authentifizierungsfehlern.

Related MCP server: YNAB Assistant

Voraussetzungen

• Node.js 22 oder neuer.

• Money Lover-Zugangsdaten.

Installation

npm install

Verwendung

Starten Sie den MCP-Server über stdio:

npm start

Projektbezogene Konfiguration (Claude Code)

Fügen Sie .mcp.json im Projektstammverzeichnis hinzu:

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "node",
      "args": ["/absolute/path/to/moneylover-mcp/src/server.js"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

Und aktivieren Sie es in .claude/settings.json:

{ "enabledMcpjsonServers": ["mcp-moneylover"] }

Globale Konfiguration (Claude Desktop / Cursor)

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "npx",
      "args": ["@ferdhika31/moneylover-mcp@latest"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

Verfügbare Tools

Auth

Benutzer

Geldbörsen (Wallets)

Kategorien

Transaktionen

Statik & Konfiguration

Beispiele für die Tool-Verwendung

Beispiele für Prompts, erforderliche vs. optionale Felder, Fallstricke und gängige mehrstufige Muster für jedes Tool: docs/examples.md.

Bibliotheksverwendung

import { MoneyloverClient } from './src/moneyloverClient.js';

const token = await MoneyloverClient.getToken(email, password);
const client = new MoneyloverClient(token);

const wallets = await client.getWallets();
const txns = await client.getTransactions(walletId, '2026-01-01', '2026-04-30');
await client.addTransaction({ walletId, categoryId, amount: '50000', date: '2026-04-18' });
await client.editTransaction('txn-id', { amount: '60000', note: 'updated' });
await client.deleteTransaction('txn-id');

Testen

Unit-Tests

Gemockte Unit-Tests – keine Live-API-Aufrufe erforderlich:

npm test

Integrationstests (mcp-tester)

mcp-tester ist ein auf ReAct-Agenten basierendes MCP-Testframework. Es startet den Server, steuert ein LLM zur Ausführung von Tools als Reaktion auf natürlichsprachliche Prompts und prüft, ob die korrekten Tools mit den korrekten Argumenten aufgerufen wurden.

Installation

pipx install --index-url https://pypi.artifacts.furycloud.io/simple/ mcp-tester

Konfiguration

tests/mcp-tester/mcps.json – verweisen Sie auf den lokalen Server mit Ihren Zugangsdaten:

{
  "mcp-moneylover": {
    "command": "node",
    "args": ["/absolute/path/to/src/server.js"],
    "transport": "stdio",
    "env": {
      "EMAIL": "your@email.com",
      "PASSWORD": "your-password"
    }
  }
}

Ausführung

mcp-tester run-tests \
  --mcps tests/mcp-tester/mcps.json \
  --model gpt-4o-mini \
  --concurrent-runs 3 \
  tests/mcp-tester/read-tools.yaml

Ergebnisse

tests/mcp-tester/read-tools.yaml enthält 25 Integrationstests, die jedes Lese-Tool abdecken:

total 25, success 25, failures 0

Die wichtigsten Entscheidungen, die die Tests stabil machen:

• Kein Token-Parameter bei Lese-Tools – das Offenlegen eines optionalen token-Feldes führte dazu, dass LLMs Geldbörsen-IDs dort einfügten. Der Server authentifiziert sich automatisch über Umgebungsvariablen.

• Antwortkürzung – mehrere Endpunkte geben Hunderttausende von Datensätzen aus der gemeinsam genutzten MoneyLover-Datenbank zurück. Tools akzeptieren einen limit-Parameter (Standard: 20–100), um den LLM-Kontext unter Kontrolle zu halten.

• Dict-Wrapping – alle Tool-Antworten geben ein JSON-Objekt zurück (niemals ein reines Array), damit die Validierung des MCP-Frameworks erfolgreich ist.

Schreib-Tool-Tests (mcp-tester)

Drei zusätzliche YAML-Dateien testen den vollständigen CRUD-Lebenszyklus für Geldbörsen, Kategorien und Transaktionen in drei aufeinanderfolgenden Phasen. Jede Phase führt alle drei Ressourcentypen gleichzeitig aus.

Führen Sie die Phasen nacheinander aus – jede hängt von der vorherigen ab:

# Phase 1: Create
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-create.yaml

# Phase 2: Edit (after Phase 1 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-edit.yaml

# Phase 3: Delete (after Phase 2 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-delete.yaml

Ergebnisse über alle drei Phasen hinweg:

Phase 1 (Create): total 3, success 3, failures 0
Phase 2 (Edit):   total 3, success 3, failures 0
Phase 3 (Delete): total 3, success 3, failures 0

Die wichtigsten Designentscheidungen für Schreib-Tool-Tests:

• Erkennung vor Mutation – Tests zum Bearbeiten und Löschen weisen den Agenten an, zuerst ein Lese-Tool (get_wallets, get_categories, get_transactions) aufzurufen, um das Ziel anhand des Namens zu finden, und dann das Mutations-Tool aufzurufen. Dies spiegelt das reale Verhalten von Agenten wider, bei denen IDs nicht im Voraus bekannt sind.

• args: !any für Schreib-Tool-Assertionen – Das Framework erfordert eine exakte Übereinstimmung der Argumente. Schreib-Tools akzeptieren optionale Felder (icon, with usw.), die der Agent nach eigenem Ermessen einfügen kann; !any überprüft, ob das Tool aufgerufen wurde und erfolgreich war, ohne bei harmlosen Extras zu scheitern. Assertionen für Lese-Tools können exakte Argumentübereinstimmungen verwenden, da deren Schemata keine optionalen Felder enthalten, die das LLM spontan hinzufügen würde.

• Vorhersehbare Bezeichner – Testressourcen verwenden feste Namen (MCP-Test-Wallet, MCP-Test-Category) und eine feste Notiz (MCP test transaction), damit der Agent sie während der Bearbeitungs- und Löschphasen anhand des Namens finden kann, ohne den Status zwischen Testläufen teilen zu müssen.

• Vollständige Payload-Bearbeitungs-Assertionen – edit_transaction ist ein Vorgang, der den gesamten Datensatz ersetzt; der Test-Prompt weist den Agenten an, zuerst die vorhandene Transaktion abzurufen (get_transactions) und alle aktuellen Feldwerte zu übernehmen, wobei nur die Notiz geändert wird. Dies validiert das mehrstufige Denken, das die Tool-Beschreibung erfordert.

Sicherheitshinweise

• Committen Sie niemals echte Zugangsdaten oder Token.

• Zwischengespeicherte Token befinden sich in ~/.moneylover-mcp/ und sind auf den aktuellen Benutzer beschränkt.

• Löschen Sie dieses Verzeichnis, um alle zwischengespeicherten Sitzungen zu widerrufen.