expense-tracker-mcp

Ein Remote-MCP-Server zur Erfassung persönlicher Ausgaben, basierend auf Postgres, entwickelt für zwei verschiedene Clients: Claude als Connector und einen benutzerdefinierten LangGraph-Agenten.

Erfasse eine Ausgabe mit „450 für Lebensmittel ausgegeben heute“ und frage dann „Was habe ich diesen Monat für Essen ausgegeben?“ – und erhalte von beiden Clients dieselbe Antwort, weil der Zustand in einer Datenbank und nicht in einer Chat-Sitzung liegt.

Claude (connector) ─┐
                    ├─► expense-tracker-mcp ─► Neon Postgres
LangGraph agent ────┘        (FastMCP)

Status

Phase 1 ist Ende-zu-Ende gegen eine echte Neon-Datenbank verifiziert. Die Bereitstellung ist der nächste Schritt.

Related MCP server: expense-tracker-mcp-server

Tools

Zusätzlich eine Ressource, expenses://categories, die die vollständige Taxonomie offenlegt, sodass ein Client die gültigen Werte im Voraus lesen kann, anstatt sie aus abgelehnten Schreibvorgängen zu entdecken.

Kategorien sind eine feste zweistufige Taxonomie, definiert in categories.json – 20 Kategorien, jeweils mit Unterkategorien. Alles außerhalb davon wird abgelehnt, wobei die gültigen Werte in der Fehlermeldung enthalten sind, sodass das Modell sich in einem einzigen Roundtrip korrigieren kann.

Lokal ausführen

Voraussetzungen: Python 3.10+, uv und ein Neon-Konto (der kostenlose Tarif reicht aus).

git clone https://github.com/<your-username>/expense-tracker-mcp
cd expense-tracker-mcp
uv sync

Datenbank konfigurieren. Kopiere die Beispieldatei und fülle deine Neon-Verbindungszeichenfolge aus:

cp .env.example .env      # PowerShell: Copy-Item .env.example .env

Zwei Dinge sind bei dieser Zeichenfolge wichtig:

• Verwende die gepoolte Verbindung – der Host enthält -pooler.

• Entferne die ?sslmode=require&channel_binding=require-Query-Zeichenfolge. asyncpg akzeptiert die Query-Parameter von libpq nicht und wirft invalid dsn: invalid connection option "sslmode". TLS wird stattdessen explizit im Code angefordert. (Der Server entfernt diese ebenfalls defensiv, sodass eine roh eingefügte Zeichenfolge trotzdem funktioniert.)

Tabelle erstellen. Führe schema.sql einmal aus, im Neon SQL Editor oder einem beliebigen Postgres-Client. Jede Anweisung ist idempotent.

Server starten:

uv run python main.py            # http://127.0.0.1:8000/mcp

Oder interaktiv erkunden mit dem MCP Inspector (benötigt Node):

uv run fastmcp dev inspector main.py

Ein Browser-GET auf /mcp gibt 406 Not Acceptable zurück. Das ist korrekt, kein Fehler – MCP erfordert POST mit Accept: application/json, text/event-stream.

Bereitstellen

Entwickelt für Prefect Horizon (ehemals FastMCP Cloud). Verweise auf dieses Repository mit Entrypoint main.py:mcp und setze DATABASE_URL in den Umgebungsvariablen. Bereitgestellte Server erhalten eine *.fastmcp.app-URL, die direkt als Connector zu Claude hinzugefügt werden kann.

Beachte, dass es bewusst keine .python-version-Datei gibt. Horizon baut mit UV_PROJECT_ENVIRONMENT=/usr/local, einem System-Python-Präfix statt einer virtuellen Umgebung; eine Versions-Pin führt dazu, dass uv sie ablehnt, ein verwaltetes CPython herunterlädt und beim Versuch, ein Nicht-venv-Verzeichnis neu zu erstellen, fehlschlägt. Die requires-python = ">=3.10"-Untergrenze in pyproject.toml ist ausreichend.

Designentscheidungen

Geld ist NUMERIC(12,2), niemals ein Float. Binäre Gleitkommazahlen können 0.1 nicht exakt darstellen, daher summiert sich bei Float-Beträgen ein Fehler auf und Summen weichen um Cent ab. Beträge sind Decimal in Python, NUMERIC in Postgres und werden als Strings über die Leitung übertragen – JSON-Zahlen sind IEEE-754-Doubles, daher würde die Serialisierung als Float die Abweichung im letzten Schritt wieder einführen. 450.55 + 120.45 ergibt exakt 571.00.

Der Verbindungspool wird lazy erstellt, niemals beim Import. Eine Verbindung beim Import verwandelt ein vorübergehendes Datenbankproblem in einen fehlgeschlagenen Deploy; ein Lazy-Pool macht daraus einen einzelnen fehlgeschlagenen Tool-Aufruf, den der Aufrufer wiederholen kann. Die Schemaerstellung ist ebenfalls ein separates einmaliges Skript, nicht etwas, das der Server beim Start ausführt.

Jeder Parameter ist annotiert. FastMCP erstellt das JSON-Schema, das das Modell sieht, aus Typ-Hinweisen, sodass date: date das Modell als {"type": "string", "format": "date"} erreicht und amount exclusiveMinimum: 0 trägt. Unannotierte Parameter verschlechtern messbar die Genauigkeit des Tool-Aufrufs – und ungültige Eingaben werden durch Schema-Validierung abgelehnt, bevor der Tool-Body überhaupt ausgeführt wird.

Jedes Tool gibt ein Dict zurück, sowohl bei Erfolg als auch bei Fehler, mit einem ok-Schlüssel. Ein Tool, das bei Erfolg eine Liste und bei Fehler ein Dict zurückgibt, zwingt jeden Aufrufer, vor der Verwendung des Ergebnisses eine Typüberprüfung durchzuführen.

user_id existiert von Anfang an, standardmäßig gesetzt und derzeit ungenutzt; Phase 4 beschränkt jede Abfrage darauf. Das spätere Hinzufügen einer NOT NULL-Spalte zu einer befüllten Tabelle ist eine Migration – sie jetzt hinzuzufügen ist kostenlos. Sie ist bewusst kein Tool-Parameter: Wenn das Modell die user_id wählen könnte, könnte jeder Client die Ausgaben jedes Benutzers lesen, nur indem er danach fragt.

Logging geht nach stderr. Über den stdio-Transport ist stdout der JSON-RPC-Kanal, und ein versehentliches print() beschädigt den Protokollstrom.

Noch nicht implementiert

Ehrliche Einschränkungen statt Versehen:

• Keine Bearbeitungs- oder Lösch-Tools. Das Korrigieren einer falsch erfassten Ausgabe bedeutet, direkt auf die Datenbank zuzugreifen. Aufgeschoben, bis es sich in der Praxis als störend erweist.

• Keine Währungsspalte. Jeder Betrag wird als in einer Währung angenommen.

• Keine Authentifizierung. Jede Ausgabe wird als user_id = 'default' geschrieben, daher ist der bereitgestellte Server bis Phase 4 Single-Tenant.

Layout

main.py           the server: three tools, one resource
schema.sql        one-time table + index creation
categories.json   the category taxonomy, single source of truth
.env.example      documents DATABASE_URL

Erstellt mit

FastMCP 3 · asyncpg · Neon Postgres