Expense Tracker Agent

Ein KI-gestützter persönlicher Ausgaben-Tracker, der natürlichsprachliche Anfragen in strukturierte Datenbankoperationen umwandelt. Das Projekt kombiniert eine responsive Streamlit-Oberfläche, Claude-Toolnutzung, einen MCP-Server und lokale SQLite-Speicherung.

Was dieses Projekt demonstriert

• Agentischer, mehrstufiger Tool-Einsatz für reale Datenbank-Workflows

• Eine saubere Trennung zwischen Sprachmodell, MCP-Transport und Datenebene

• Eine direkte Claude-Toolaufruf-Schleife ohne Orchestrierungsframework

• Eingabevalidierung, eingeschränktes Assistentenverhalten und sichere lokale Datenverarbeitung

• Automatisierte Smoke-Tests und kontinuierliche Integration

• Eine responsive Benutzeroberfläche für Eingabe, Konversation und Ausgaben-Einblicke

Related MCP server: Expense Tracker MCP Server

Produktfunktionen

• Ausgaben über ein Formular oder eine natürlichsprachliche Anfrage hinzufügen

• Datum, Betrag, Kategorie und Beschreibung für jede Transaktion speichern

• Ausgaben über MCP-Tools suchen, aktualisieren, löschen und zusammenfassen

• Gesamtbeträge, aktuelle Transaktionen und Ausgaben auf Kategorieebene anzeigen

• Den fokussierten Finanzassistenten nach datenbankgestützten Erkenntnissen fragen

• Ausgabendaten lokal in einer SQLite-Datei speichern

Architektur

flowchart LR
    U[User] --> UI[Streamlit or CLI]
    UI --> A[Claude agent]
    A -->|Tool request| C[MCP client]
    C -->|stdio| S[MCP server]
    S -->|DB-API 2.0| D[(SQLite)]
    D --> S
    S -->|Structured result| A
    A --> UI

Claude greift nie direkt auf SQLite zu. Es wählt aus den MCP-Tool-Schemata aus, und der Server führt jede validierte Datenbank-Lese- und Schreiboperation durch.

Beispielhafte Agent-Workflows

Technologie

Schnellstart

Voraussetzungen:

• Python 3.11 oder neuer

• Ein Anthropic-API-Schlüssel für den Assistenten

Virtuelle Umgebung erstellen und aktivieren:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Für macOS oder Linux die Umgebung aktivieren mit:

source .venv/bin/activate

Lokale Umgebungsdatei erstellen und ANTHROPIC_API_KEY hinzufügen:

Copy-Item .env.example .env

Datenbankschema und Startkategorien erstellen, dann die App starten:

python db_setup.py
streamlit run streamlit_app.py

Der MCP-Server verwendet stdio und startet automatisch, wenn ein Client verbindet.

Qualitätsprüfungen

Entwicklungsabhängigkeiten installieren und die gleichen Prüfungen wie in der CI ausführen:

python -m pip install -r requirements-dev.txt
python -m black --check .
python -m compileall -q agent.py client_test.py db_setup.py mcp_client.py server.py streamlit_app.py
python -m pytest -q
python client_test.py

client_test.py führt alle 18 MCP-Tools aus und entfernt seine temporären Datensätze, wenn der Smoke-Test beendet ist.

MCP-Tools

Der Server stellt 18 Tools bereit:

• Kategorienverwaltung: list_categories, add_category, rename_category, delete_category, get_category_name

• Ausgabenverwaltung: add_expense, update_expense, delete_expense, list_expenses, search_expenses, expenses_by_category, total_expense_by_category, total_expense, monthly_summary

• Unterstützende Abfragen: current_date, find_category, get_expense, expenses_between

Projektstruktur

Konfiguration

Die .env-Datei und expenses.db sind von Git ausgeschlossen. API-Schlüssel und persönliche Ausgabendaten bleiben außerhalb des Repositorys.

Um die Datenbank mit einer leeren Ausgabentabelle neu zu erstellen:

python db_setup.py --reset