Personal Expense Tracker MCP

Was dieses Projekt tut

Personal Expense Tracker MCP ist ein einfacher, lokaler MCP-Server für die Erfassung persönlicher Ausgaben.

Er speichert die Ausgabendaten in einer lokalen CSV-Datei.

Der Server stellt einem MCP-Client fünf gezielte Tools bereit:

• eine neue Ausgabe hinzufügen

• gespeicherte Ausgaben auflisten

• eine Ausgabenübersicht erstellen

• eine vorhandene Ausgabe aktualisieren

• eine vorhandene Ausgabe löschen

Das Projekt ist bewusst einfach gehalten und soll sich leicht lokal ausführen lassen.

Es sind weder ein Bankkonto noch eine externe API erforderlich.

Related MCP server: expense-mcp

Voraussetzungen

Bevor du beginnst, stelle sicher, dass Folgendes installiert ist:

• Node.js Version 20 oder neuer

• npm

• Git

Prüfe Node.js.

node --version

Prüfe npm.

npm --version

Prüfe Git.

git --version

Installation

1 Repository klonen

git clone https://github.com/MohammadYousef-001/Personal-Expenses-Tracker.git

2 In den Projektordner wechseln

cd Personal-Expenses-Tracker

3 Die Pakete installieren

npm install

Warte, bis npm die benötigten Pakete installiert hat.

Datendatei

Die Ausgaben werden lokal gespeichert in:

data/expenses.csv

Die CSV-Datei verwendet diese Spalten:

id,amount,category,date,description

Ändere die Spaltennamen nicht.

MCP-Server starten

Zum Starten des Servers führe Folgendes aus:

npm run dev

Der Server nutzt die Standard-Eingabe und -Ausgabe für die MCP-Kommunikation. Er ist ein lokaler Server und benötigt keinen Web-Port.

MCP Inspector starten

MCP Inspector ist der einfachste Weg, die Tools manuell zu testen.

Führe Folgendes aus:

npm run inspect

Es sollte sich ein Browserfenster mit MCP Inspector öffnen.

Falls es sich nicht automatisch öffnet, verwende die im Terminal angezeigte URL.

Im Inspector

1. verbinde dich mit dem Server

2. öffne den Abschnitt Tools

3. wähle ein Tool aus

4. gib die Eingabe ein

5. klicke auf Execute Tool

6. prüfe das Ergebnis

Verfügbare Tools

Tool 1 add_expense

Verwende add_expense, um eine neue Ausgabe zu speichern.

Eingaben

amount

Der ausgegebene Geldbetrag.

Er muss eine positive Zahl sein.

category

Die Ausgabenkategorie.

Beispiele

groceries
transport
bills
shopping

Die Kategorie wird in Kleinbuchstaben gespeichert, damit die Kategorienamen konsistent bleiben.

date

Das Ausgabedatum.

Es muss folgendes Format verwenden:

YYYY-MM-DD

Beispiel

2026-08-12

Das Datum muss außerdem ein echtes Kalenderdatum sein.

Das ist ungültig:

2026-99-99

description

Optionale kurze Information zur Ausgabe.

Beispiel

{
  "amount": 25,
  "category": "groceries",
  "date": "2026-08-12",
  "description": "milk and bread"
}

Eine erfolgreiche Anfrage speichert die Ausgabe in folgender Datei:

data/expenses.csv

Tool 2 list_expenses

Verwende list_expenses, um gespeicherte Ausgaben anzusehen.

Ohne Filter

{}

Nach Kategorie filtern

{
  "category": "groceries"
}

Nach Monat filtern

{
  "month": "2026-08"
}

Beide Filter verwenden

{
  "month": "2026-08",
  "category": "groceries"
}

Der Monat muss folgendes Format verwenden:

YYYY-MM

Der Monat muss zwischen 01 und 12 liegen.

Das ist ungültig:

2026-99

Tool 3 get_spending_summary

Verwende get_spending_summary, um eine Übersicht deiner Ausgaben zu erhalten.

Beispiel

{
  "month": "2026-08"
}

Das Ergebnis kann enthalten:

• den ausgewählten Monat

• den insgesamt ausgegebenen Betrag

• die Anzahl der Ausgaben

• die Ausgabensumme pro Kategorie

Beispielergebnis

month: 2026-08
total amount: 150
expense count: 4

category totals:
groceries: 80
transport: 30
bills: 40

Die tatsächlichen Werte hängen von den Daten in data/expenses.csv ab.

Beispiel-Prompts

Ausgabe hinzufügen

I spent 25 on groceries today

Dafür kannst du Folgendes verwenden:

add_expense

Ausgaben finden

show my grocery expenses for this month

Dafür kannst du Folgendes verwenden:

list_expenses

Ausgaben überprüfen

how much did I spend this month

Dafür kannst du Folgendes verwenden:

get_spending_summary

Eingabevalidierung

Das Projekt prüft die Tool-Eingaben, bevor sie verwendet werden.

Beispiele für ungültige Eingaben:

• negativer Betrag

• Betrag von null

• falsches Datumsformat

• unmögliches Kalenderdatum

• ungültiger Monat

• zu lange Kategorie

• zu lange Beschreibung

Ungültige Eingaben werden abgewiesen, bevor sie gespeichert werden.

Schemata testen

Führe Folgendes aus:

npm run check:schema

Bei einer erfolgreichen Ausführung sollte Folgendes angezeigt werden:

All expense schemas are valid.

Fehlerbehebung

Problem 1: Pakete fehlen

Wenn eine Fehlermeldung angezeigt wird, dass ein Paket oder Modul nicht gefunden werden kann, führe Folgendes aus:

npm install

Versuche es danach erneut.

npm run dev

Problem 2: MCP Inspector startet nicht

Stelle sicher, dass die Pakete installiert sind:

npm install

Dann führe Folgendes aus:

npm run inspect

Falls noch ein alter Inspector-Prozess läuft, drücke:

Ctrl + C

Starte den Inspector danach erneut.

Problem 3: TypeScript- oder Schema-Fehler

Führe Folgendes aus:

npm run check:schema

Wenn alles korrekt ist, sollte Folgendes angezeigt werden:

All expense schemas are valid.

Wenn ein Fehler auftritt, prüfe den Dateinamen und die im Terminal angezeigte Zeilennummer. Behebe den Fehler, bevor du den Inspector erneut startest.

Problem 4: Ungültiges Datum

Ein gültiges Datum muss folgendes Format verwenden:

YYYY-MM-DD

Gültiges Beispiel

2026-08-12

Ungültiges Beispiel

2026-99-99

Problem 5: Keine Ausgaben werden zurückgegeben

Prüfe:

data/expenses.csv

Stelle sicher, dass unterhalb der CSV-Kopfzeile Ausgabenzeilen vorhanden sind.

Wenn die Datei nur die Kopfzeile enthält, ist ein leeres Ergebnis normal.

Projektstruktur

Wichtige Projektdateien:

Personal-Expenses-Tracker/
│
├── data/
│   └── expenses.csv
│
├── docs/
│   ├── design.md
│   └── threat-model.md
│
├── examples/
│
├── src/
│   ├── index.ts
│   ├── schemas/
│   ├── tools/
│   └── lib/
│
├── SECURITY.md
├── package.json
└── README.md

Sicherheit

Tool-Eingaben werden als nicht vertrauenswürdige Eingaben behandelt.

Das Projekt validiert Eingaben, bevor wichtige Vorgänge ausgeführt werden.

Der Pfad zur Ausgabendatei wird von der Anwendung kontrolliert.

Fehler, die an den MCP-Client zurückgegeben werden, werden kurz gehalten.

Weitere Details zu Fehlern bleiben für Debugging-Zwecke im lokalen Terminal.

Die Ausgaben-Tools benötigen keine externen Netzwerkanfragen.

Weitere Sicherheitsinformationen findest du in:

SECURITY.md

Projektumfang

Dieses Projekt ist ein kleiner, lokaler Ausgaben-Tracker für persönliche Ausgaben.

Enthalten sind nicht:

• Bankverbindungen

• automatische Bankimporte

• Benutzeranmeldung

• Cloud-Datenbank

• vollständige grafische Anwendung

• Finanzprognosen

Das Hauptziel ist es, einfache MCP-Tools für die lokale Ausgabenverfolgung bereitzustellen.

Lizenz

Dieses Projekt verwendet die MIT License.

Siehe LICENSE.