Daten und Synchronisation
Beträge
Abschnitt betitelt „Beträge“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.
Mit YNAB sprechen
Abschnitt betitelt „Mit YNAB sprechen“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.
Plans, früher Budgets
Abschnitt betitelt „Plans, früher Budgets“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 Referenzen von YNAB
Abschnitt betitelt „Die Referenzen von YNAB“- Dokumentation der YNAB-API – Endpunkte, Authentifizierung, Anfragelimit
- OpenAPI-Spezifikation – die Quelle der Seite YNAB-API-Abdeckung
- Änderungsprotokoll der YNAB-API – Version 1.79.0, veröffentlicht am 05.03.2026:
/budgetswurde in/plansumbenannt - Navigating Multiple Plans in YNAB
- How to Adjust Your Plan Settings
Die lokale Kopie der Transaktionen
Abschnitt betitelt „Die lokale Kopie der Transaktionen“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:
- Das erste Laden fragt nach jeder Transaktion und behält den
server_knowledgevon YNAB, einen Änderungszähler. - Das nächste Laden sendet
last_knowledge_of_serverund erhält nur, was sich seither geändert hat: neue, geänderte und gelöschte Transaktionen. - 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.
Das Anfragelimit von YNAB
Abschnitt betitelt „Das Anfragelimit von YNAB“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.
Wenn YNAB keine Antwort gibt
Abschnitt betitelt „Wenn YNAB keine Antwort gibt“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.
Was nie gespeichert wird
Abschnitt betitelt „Was nie gespeichert wird“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