Zum Inhalt springen

Daten und Synchronisation

YNAB speichert jeden Betrag als ganze Zahl von Milliunits: 1,00 ist 1000, −12,34 ist -12340. avenir-mcp rechnet an der Grenze um und zeigt dem Agenten nie Milliunits:

Richtung Regel
YNAB → Agent milliunits / 1000
Agent → YNAB round(amount × 1000): 111,32 wird genau 111320

Summen, Differenzen und anteilige Aufteilungen werden in Milliunits berechnet und dann einmal umgerechnet, sodass kein Rundungsfehler einen Cent erzeugen oder verlieren kann. Beträge sind in der Währung des Plans; Ausgaben sind negativ, Eingänge positiv.

client.py ist das einzige Modul, das die API von YNAB aufruft:

Basis-URL https://api.ynab.com/v1 oder AVENIR_MCP_YNAB_URL
Authentifizierung Authorization: Bearer <YNAB_API_KEY> bei jeder Anfrage
Verwendete Methoden GET zum Lesen; PATCH, POST und DELETE auf Transaktionen, Kategorien und Monatsbudgets
Fehler jeder 4xx- oder 5xx-Status kommt als Error calling tool '<tool>': YNAB <status>: <detail> zurück, mit der eigenen Erklärung von YNAB

plan_id akzeptiert last-used: YNAB setzt dafür den Plan ein, den Sie zuletzt geöffnet haben.

Im API-Änderungsprotokoll von YNAB ist vermerkt, dass in der am 05.03.2026 veröffentlichten Version 1.79.0 /budgets in /plans umbenannt wurde: Die Spezifikation dokumentiert nur noch Pfade /plans. avenir-mcp folgt ihr: Sein Client ruft /plans auf, und seine Tools sagen list_plans und plan_id. Das Wort budget bleibt, wo YNAB es behält, für das einer Kategorie zugewiesene Geld (budgeted, angezeigt als Assigned), daher set_category_budget und get_budget_vs_actual.

Die meisten Tools brauchen die Transaktionen des Plans: um Ausstehendes zu finden, aus der Historie zu lernen, mit der Bank zu vergleichen, vorauszurechnen. Sie bei jedem Aufruf alle herunterzuladen wäre langsam und würde das Kontingent von YNAB verbrauchen. avenir-mcp hält eine Kopie je Plan im Speicher und aktualisiert sie mit der Delta-Synchronisation von YNAB:

  1. Das erste Laden fragt nach jeder Transaktion und behält den server_knowledge von YNAB, einen Änderungszähler.
  2. Das nächste Laden sendet last_knowledge_of_server und erhält nur, was sich seither geändert hat: neue, geänderte und gelöschte Transaktionen.
  3. avenir-mcp führt sie in seine Kopie zusammen: Eine geänderte Transaktion ersetzt die alte, eine gelöschte wird entfernt.

Mit der ID eines Plans wird die Kopie per Delta-Synchronisation aktualisiert. Mit last-used, das den zuletzt in YNAB geöffneten Plan meint und sich zwischen zwei Aufrufen ändern kann, werden die Transaktionen jedes Mal vollständig geladen – immer noch eine Anfrage –, damit zwei Plans nie vermischt werden. Bei mehreren Plans übergeben Sie die ID aus list_plans.

Die Kopie lebt so lange wie der Serverprozess. Gefilterte Lesevorgänge – nach Datum oder nach Kategorie – umgehen sie.

YNAB erlaubt 200 Anfragen pro Stunde und Token, in einem gleitenden Fenster. Was jedes Tool bei leerem Cache kostet, wird auf dem Demo-Plan gemessen und auf seiner Referenzseite angegeben:

Kosten Tools
0 jeder durch die Prüfung abgelehnte Aufruf (ein fehlerhafter Monat, ein leerer Name…)
1 list_plans, list_accounts, list_category_groups, get_monthly_summary, get_age_of_money, get_category_balances, get_budget_vs_actual, get_underfunded_targets, get_debt_payoff_plan, approve_transactions, eine Vorschau von set_category_budget, eine Vorschau von move_money, eine Vorschau von flag_transactions, eine Vorschau von set_category_target
2 get_net_worth_trend, get_runway, get_debt_payoff_plan ohne monthly_budget, wenn eine Mindestzahlung fehlt, reconcile_account, create_transactions, create_category, update_category, list_payees, eine Vorschau von rename_payee, undo_operation
3 get_runway mit essential_groups, get_savings_rate, find_transactions, find_recurring_charges, list_scheduled_transactions, suggest_categories (eine ganze Seite), apply_categories, eine Vorschau von split_transaction
4 forecast_balance
1 + N get_spending_trends über N Monate

Das Anwenden einer bestätigten Schreibaktion fügt eine eigene Anfrage hinzu (ein gebündeltes PATCH für beliebig viele Transaktionen). Mit warmem Cache kostet das erneute Lesen der Transaktionen eine kleine Delta-Anfrage.

Ist das Kontingent aufgebraucht, antwortet YNAB mit 429, und diese Antwort wird nie erneut versucht: avenir-mcp gibt … YNAB 429: … zurück und sendet 10 Minuten lang überhaupt keine Anfrage – oder für die Anzahl der Sekunden, die im Retry-After-Header von YNAB angegeben ist, wenn die Antwort einen solchen Header trägt (gehalten zwischen 1 Minute und 1 Stunde). Außerdem hört avenir-mcp von selbst bei 180 Anfragen in der letzten Stunde auf, lässt den Rest anderen Apps mit demselben Token und sagt, in wie vielen Minuten die nächste Anfrage gehen kann. In beiden Fällen wird der Agent angewiesen, es Ihnen zu sagen und es vorher nicht erneut zu versuchen.

Ein Lesevorgang, der unterwegs fehlschlägt – ein Timeout, eine abgelehnte Verbindung, ein 502, ein 503 oder ein 504 –, wird erneut gesendet, insgesamt dreimal, mit einer kurzen Wartezeit, die sich dazwischen verdoppelt. Einen Lesevorgang zu wiederholen ändert nichts, es kostet Sie also nur Anfragen, und jeder Versuch wird auf die 180 der Stunde angerechnet.

Bei einem Schreibvorgang ist es anders. Sobald ein POST, ein PATCH oder ein DELETE gegangen ist, sendet avenir-mcp ihn nie erneut: YNAB hat ihn möglicherweise schon angewendet und in eine Verbindung geantwortet, die es nicht mehr gab, und eine zweite Kopie würde eine zweite Transaktion oder eine zweite Änderung anlegen. Der einzige Fehler, der einen Schreibvorgang erneut sendet, ist der, der beweist, dass er nie gegangen ist, etwa eine abgelehnte Verbindung.

Ein Schreibvorgang, auf den keine Antwort zurückkam, endet also in einer Antwort, die genau das sagt: Die Änderung ist vielleicht angewendet, vielleicht nicht, und der Agent wird angewiesen, mit find_transactions oder get_category_balances nachzusehen, statt ihn zu wiederholen. Ein Lesevorgang, der nie durchkam, sagt dagegen, dass nichts geändert wurde und dass er in wenigen Minuten erneut angefordert werden kann.

avenir-mcp legt keine Kopie auf der Festplatte ab. Die Transaktionen leben im Speicher, solange der Server läuft; das Journal enthält nur IDs, die bei einer Budgetänderung oder Umschichtung zugewiesenen Beträge, das wiederherzustellende Ziel und die beiden Namen eines umbenannten Zahlungsempfängers; das Token bleibt in der Umgebung und wird nie protokolliert.

Inoffizielles Projekt. „We are not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at https://www.ynab.com. The names YNAB and You Need A Budget, as well as related names, tradenames, marks, trademarks, emblems, and images are registered trademarks of YNAB.“ Wir sind mit YNAB oder einer seiner Tochtergesellschaften oder verbundenen Unternehmen weder verbunden noch assoziiert noch in irgendeiner Weise offiziell verknüpft. Die offizielle Website von YNAB finden Sie unter https://www.ynab.com. Die Namen YNAB und You Need A Budget sowie zugehörige Namen, Handelsnamen, Zeichen, Marken, Embleme und Bilder sind eingetragene Marken von YNAB. avenir-mcp wird ohne Gewähr bereitgestellt und ist keine Finanzberatung. Rechtliche Hinweise · Datenschutz