Installation
Diese Seite führt Sie in etwa zehn Minuten von null zu einem funktionierenden avenir-mcp. Jeder Schritt endet mit einer Prüfung, damit Sie wissen, dass er geklappt hat, bevor Sie weitermachen.
- uv installieren, das Tool, das avenir-mcp ausführt.
- Ein YNAB-Token besorgen, den Zugang von avenir-mcp zu Ihren Plans.
- Prüfen, ob avenir-mcp startet, einmal von Hand.
- avenir-mcp zu Ihrem Client hinzufügen.
- Prüfen, ob es funktioniert, mit einer ersten Frage.
- Änderungen erlauben, wenn der Agent für Sie aufräumen soll.
Was Sie brauchen
Abschnitt betitelt „Was Sie brauchen“| Wozu | Woher | |
|---|---|---|
| Ein YNAB-Konto | avenir-mcp liest und ändert Ihre Plans | app.ynab.com |
| Einen MCP-Client | die Anwendung, mit der Sie sprechen; sie startet avenir-mcp | Claude Code, Claude Desktop, Cursor, VS Code… |
| uv | lädt avenir-mcp und das nötige Python herunter und führt sie in einer isolierten Umgebung aus | der nächste Schritt |
Sie müssen Python nicht installieren, das Repository nicht klonen und keine virtuelle Umgebung anlegen: Das alles erledigt uv.
uv installieren
Abschnitt betitelt „uv installieren“In einem Terminal:
curl -LsSf https://astral.sh/uv/install.sh | shOder mit Homebrew: brew install uv.
In PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Oder mit WinGet: winget install --id=astral-sh.uv -e.
Schließen Sie das Terminal und öffnen Sie es erneut, dann prüfen Sie:
uv --versionEs wird eine Version ausgegeben, etwa uv 0.12.19. Command not found? Der Installer
fügt uv nur dem PATH neuer Terminals hinzu: Öffnen Sie ein neues. Details in der
Dokumentation von uv.
Ein YNAB-Token besorgen
Abschnitt betitelt „Ein YNAB-Token besorgen“- Melden Sie sich bei YNAB in einem Webbrowser an, unter app.ynab.com – die mobilen Apps zeigen die Entwicklereinstellungen nicht.
- Klicken Sie oben links auf Ihren Namen, dann auf Account Settings.
- Öffnen Sie Developer Settings.
- Klicken Sie unter Personal Access Tokens auf New Token, geben Sie Ihr YNAB-Passwort ein, dann Generate.
- Kopieren Sie das oben auf der Seite angezeigte Token: eine lange Folge aus Buchstaben, Ziffern und Bindestrichen. YNAB zeigt es nur ein einziges Mal. Wenn Sie es verlieren, legen Sie ein neues an und widerrufen Sie das alte.
Die Claude-Desktop-Erweiterung installieren
Abschnitt betitelt „Die Claude-Desktop-Erweiterung installieren“Eine einzige Datei installiert avenir-mcp, das Python, auf dem es läuft, und die Einstellungen, die es braucht. In diesem Abschnitt gibt es weder ein Terminal noch eine Konfigurationsdatei, und kein Schritt davon ist unter Windows, macOS oder Linux anders, außer wo es dort steht.
Download für Claude DesktopEs handelt sich stets um die Datei der neuesten Version; welche Version installiert wird, ist darin vermerkt, und die folgenden Schritte sind unabhängig davon immer dieselben.
-
Installieren Sie Claude Desktop, falls noch nicht geschehen, von claude.ai/download, und öffnen Sie es einmal.
-
Laden Sie die Erweiterung herunter, über die Schaltfläche oben oder über diesen Link. Sie ist etwa 17 kB groß und wird unter dem Namen
avenir-mcp.mcpbin Ihrem Download-Ordner gespeichert.Unter Windows warnen Edge oder Chrome Sie möglicherweise, dass die Datei selten heruntergeladen wird. Diese Warnung betrifft, wie selten die Datei ist, nicht ihren Inhalt: Klicken Sie auf die drei Punkte neben dem Download, dann auf Keep. Was Sie stattdessen an der Datei prüfen können, steht in SECURITY.md.
-
Ziehen Sie die Datei auf Settings → Extensions. Öffnen Sie Claude Desktop und wählen Sie anschließend Settings → Extensions: Auf diesem Bildschirm werden Ihre installierten Erweiterungen aufgelistet, und dort wird die Datei installiert. Nehmen Sie die Datei
avenir-mcp.mcpbaus Ihrem Download-Ordner oder aus der Download-Liste Ihres Browsers und ziehen Sie sie auf diesen Bildschirm. Der Installationsdialog wird geöffnet.Ein Doppelklick auf die Datei könnte ebenfalls funktionieren, sofern Ihr System
.mcpb-Dateien bereits mit Claude Desktop öffnet. Sollte Windows Sie stattdessen fragen, mit welcher Anwendung die Datei geöffnet werden soll, schließen Sie dieses Fenster:.mcpb-Dateien sind mit keiner Anwendung verknüpft, und die Suche nachclaude.exeliefert keine Ergebnisse. Ziehen Sie die Datei stattdessen auf den Bildschirm Extensions.Funktioniert keines von beiden? Öffnen Sie auf demselben Bildschirm die Advanced settings und wählen Sie unter Extension Developer die Option Install Extension…; wählen Sie die Datei aus Ihrem Download-Ordner aus.
-
Installieren Sie sie. Das Dialogfeld nennt den Namen der Erweiterung, avenir-mcp for YNAB, und sagt, was sie tut. Klicken Sie auf Install.
-
Fügen Sie Ihr Token in das Feld YNAB personal access token ein, das Token aus dem Schritt davor.
Strg+Vunter Windows und Linux,⌘+Vunter macOS. Das Feld verbirgt, was Sie einfügen; Claude Desktop verwahrt es dort, wo Ihr System Passwörter verwahrt, und es steht in keiner Datei, die Sie öffnen können. -
Lassen Sie das Kästchen Allow changes to your plans leer, und speichern Sie dann. avenir-mcp beantwortet Fragen und ändert nichts, solange das Kästchen leer bleibt. Sie können es später jederzeit ankreuzen, an derselben Stelle.
-
Prüfen Sie, ob sie da ist. Settings → Extensions führt nun avenir-mcp for YNAB auf, eingeschaltet.
-
Fragen Sie es etwas. Schreiben Sie in einem neuen Gespräch: „Liste meine YNAB-Pläne auf.“ Claude bittet Sie beim ersten Mal, das Tool zu erlauben; erlauben Sie es, und die Antwort nennt die Namen Ihrer Pläne. Die allererste Antwort dauert ein paar Sekunden länger als die danach, während Claude Desktop Python und avenir-mcp holt.
Die Installation ist fertig. Der Rest dieser Seite handelt von den anderen Clients und von der Installation von Hand; weiter mit Ihrem ersten Gespräch, oder mit Änderungen erlauben, wenn der Agent für Sie aufräumen soll.
| Um | Tun Sie |
|---|---|
| Das Token zu ändern, oder Änderungen zu erlauben | Settings → Extensions → avenir-mcp for YNAB |
| Zu aktualisieren | Laden Sie die Erweiterung erneut herunter und ziehen Sie sie auf dem Bildschirm Settings → Extensions über die bereits installierte Erweiterung; über den Link erhalten Sie stets die neueste Version |
| Zu entfernen | Entfernen Sie sie unter Settings → Extensions; das Token geht mit ihr |
Prüfen, ob avenir-mcp startet
Abschnitt betitelt „Prüfen, ob avenir-mcp startet“Bevor Sie einen Client einrichten, führen Sie avenir-mcp einmal von Hand aus. Dabei wird es heruntergeladen, und Sie sehen, dass es startet.
YNAB_API_KEY=ihr-token uvx avenir-mcp$env:YNAB_API_KEY = "ihr-token"; uvx avenir-mcpDer erste Start lädt avenir-mcp und Python herunter: einige Sekunden bis eine Minute. Danach wird nichts ausgegeben und der Befehl kehrt nicht zurück – das ist so gewollt: avenir-mcp wartet darauf, dass ein Client mit ihm spricht. Drücken Sie Strg+C, um es zu beenden.
Stattdessen erscheint ein Fehler? Siehe Fehlerbehebung.
avenir-mcp zu Ihrem Client hinzufügen
Abschnitt betitelt „avenir-mcp zu Ihrem Client hinzufügen“Wählen Sie Ihren Client. Diese Konfigurationen sind nur lesend: avenir-mcp kann Fragen beantworten, aber nichts ändern. Änderungen erlauben folgt danach. In Cursor, LM Studio und VS Code können Sie es mit einem Klick über die Schaltfläche oben auf der jeweiligen Registerkarte installieren.
In einem Terminal:
claude mcp add avenir-mcp --scope user \ --env YNAB_API_KEY=ihr-token \ -- uvx avenir-mcp| Teil | Bedeutung |
|---|---|
claude mcp add avenir-mcp |
einen MCP-Server namens avenir-mcp registrieren |
--scope user |
für alle Ihre Projekte; ohne diese Option nur für den aktuellen Ordner |
--env YNAB_API_KEY=… |
die Umgebung, mit der avenir-mcp startet |
-- |
was folgt, ist der Befehl, der den Server startet |
uvx avenir-mcp |
dieser Befehl |
Claude Code speichert das, samt Token, in ~/.claude.json, nur für Sie lesbar.
Die Erweiterung ist der kurze Weg, der ohne Terminal auskommt: Die Claude-Desktop-Erweiterung installieren.
Oder von Hand, wenn Sie die Konfiguration lieber selbst schreiben:
- Öffnen Sie Claude Desktop, dann Settings → Developer → Edit Config. Dadurch
öffnet sich
claude_desktop_config.json:- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Ist die Datei leer, fügen Sie alles Folgende ein. Listet sie bereits Server auf,
fügen Sie nur den Block
"avenir-mcp": { … }in das vorhandenemcpServersein, mit einem Komma nach dem vorherigen Eintrag.{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "ihr-token" }}}} - Speichern Sie, dann beenden Sie Claude Desktop vollständig – ⌘Q unter macOS oder über das Symbol im Infobereich unter Windows – und öffnen Sie es erneut.
- Klicken Sie auf die Schaltfläche: Cursor fordert Sie zur Bestätigung auf und fügt
anschließend
avenir-mcpzu seinen Servern hinzu. - Öffnen Sie Cursor Settings → MCP, ersetzen Sie
ihr-tokendurch das von Ihnen kopierte Token und prüfen Sie, dassavenir-mcpeingeschaltet ist.
Oder von Hand: Legen Sie ~/.cursor/mcp.json (alle Projekte) oder .cursor/mcp.json
in einem Projekt an oder öffnen Sie die Datei, und fügen Sie hinzu:
{ "mcpServers": { "avenir-mcp": { "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "ihr-token" } } }}- Klicken Sie auf die Schaltfläche: VS Code fordert Sie zur Bestätigung auf, fragt anschließend in einem Passwortfeld nach Ihrem Token und speichert dieses in seinem eigenen geheimen Speicher.
- Nutzen Sie es aus Copilot Chat im Modus Agent.
Oder von Hand: Legen Sie .vscode/mcp.json in Ihrem Arbeitsbereich an. Auch dort
fragt VS Code nach dem Token, sodass die Datei dieses niemals enthält: Eine Datei aus
einem Arbeitsbereich lässt sich leicht versehentlich in ein Repository aufnehmen.
{ "inputs": [ { "type": "promptString", "id": "ynab-token", "description": "YNAB Personal Access Token", "password": true } ], "servers": { "avenir-mcp": { "type": "stdio", "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "${input:ynab-token}" } } }}Führen Sie anschließend den Befehl MCP: List Servers aus, wählen Sie avenir-mcp,
dann Start Server.
- Öffnen Sie
~/.gemini/settings.json(legen Sie die Datei bei Bedarf an) und fügen Sie hinzu:{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "ihr-token" }}}} - Starten Sie
geminiund geben Sie/mcpein:avenir-mcperscheint mit seinen Tools. Das Modell ist das, welches Gemini CLI verwendet.
- Öffnen Sie
~/.codex/config.toml(legen Sie die Datei bei Bedarf an) und fügen Sie hinzu:[mcp_servers.avenir]command = "uvx"args = ["avenir-mcp"]env = { YNAB_API_KEY = "ihr-token" } - Starten Sie
codexund geben Sie/mcpein:avenir-mcperscheint mit seinen Tools. Das Modell ist das, welches Codex verwendet.
Für ein Modell, das auf Ihrem eigenen Rechner läuft – siehe Ein Modell wählen.
- Klicken Sie auf die Schaltfläche: LM Studio fordert Sie zur Bestätigung auf und fügt anschließend
avenir-mcpzu seiner Dateimcp.jsonhinzu. - Öffnen Sie in LM Studio den Reiter Program der rechten Seitenleiste, dann Install → Edit mcp.json, und ersetzen Sie
ihr-tokendurch das von Ihnen kopierte Token. - Speichern Sie, laden Sie ein Modell, das Tool-Aufrufe unterstützt, und beginnen Sie einen Chat: LM Studio fragt vor jedem Tool-Aufruf nach.
Oder manuell: Fügen Sie Folgendes in dieselbe Datei mcp.json ein:
{ "mcpServers": { "avenir-mcp": { "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "ihr-token" } } }}Jeder MCP-Client, der Server über stdio startet, funktioniert. Geben Sie ihm:
| Einstellung | Wert |
|---|---|
| Befehl | uvx |
| Argumente | avenir-mcp |
| Umgebung | YNAB_API_KEY = Ihr Token |
Um das Programm stattdessen in einem Container auszuführen, erstellen Sie das Image
anhand der Datei Dockerfile im Stammverzeichnis des Repositorys mit dem Befehl
docker build -t avenir-mcp .. Geben Sie anschließend dem Client docker als Befehl
und run -i --rm -e YNAB_API_KEY avenir-mcp als Argumente ein, damit das Token in der
Umgebungsvariablen statt in der Befehlszeile übermittelt wird.
Für Clients, die sich stattdessen mit einer URL verbinden, siehe Über HTTP betreiben.
Prüfen, ob es funktioniert
Abschnitt betitelt „Prüfen, ob es funktioniert“claude mcp listavenir-mcp sollte verbunden sein:
avenir-mcp: uvx avenir-mcp - ✔ ConnectedStarten Sie dann claude und geben Sie /mcp ein: avenir-mcp zeigt seine 19 Tools.
Öffnen Sie die Liste der MCP-Server oder Tools des Clients: avenir-mcp sollte
laufen, mit 19 Tools.
Fragen Sie nun in einem neuen Gespräch: „Liste meine YNAB-Pläne auf.“ Der Agent ruft
list_plans auf – Ihr Client fragt Sie
vielleicht um Erlaubnis – und antwortet mit ihren Namen. Hier der Demo-Plan, der in
dieser gesamten Dokumentation verwendet wird:
[ { "id": "demo-budget", "name": "Demo-Haushalt", "first_month": "2026-06-01", "last_month": "2026-09-01" }]avenir-mcp funktioniert. Weiter mit Ihrem ersten Gespräch oder zuerst Änderungen erlauben.
Änderungen erlauben
Abschnitt betitelt „Änderungen erlauben“Damit der Agent Transaktionen kategorisieren, Geld zwischen Kategorien verschieben oder
Konten abgleichen kann, fügen Sie der Umgebung von avenir-mcp AVENIR_MCP_WRITE=1 hinzu.
Aus der Erweiterung installiert: Öffnen Sie Settings → Extensions → avenir-mcp for YNAB, setzen Sie das Häkchen bei Allow changes to your plans, speichern Sie, und starten Sie Claude Desktop neu. Die Erweiterung setzt die Variable für Sie, es gibt nichts zu tippen.
Entfernen Sie avenir-mcp und fügen Sie es mit der zusätzlichen Variable erneut hinzu:
claude mcp remove avenir-mcp --scope userclaude mcp add avenir-mcp --scope user \ --env YNAB_API_KEY=ihr-token \ --env AVENIR_MCP_WRITE=1 \ -- uvx avenir-mcpFügen Sie die Variable neben dem Token hinzu, speichern Sie, dann starten Sie den Client neu:
"env": { "YNAB_API_KEY": "ihr-token", "AVENIR_MCP_WRITE": "1" }Fügen Sie die Variable neben dem Token in ~/.codex/config.toml hinzu, dann starten Sie Codex neu:
env = { YNAB_API_KEY = "ihr-token", AVENIR_MCP_WRITE = "1" }Der Wert muss genau 1 sein. Prüfen Sie: Der Client listet nun 32 Tools statt 19.
| Nur lesend (Standard) | Mit AVENIR_MCP_WRITE=1 |
|
|---|---|---|
| Aufgelistete Tools | 19 | 32 |
| Kategorisieren, budgetieren, abgleichen, anlegen | — | als Vorschau gezeigt, von Ihnen bestätigt, rückgängig zu machen |
| Wenn der Agent etwas missversteht | nichts kann sich ändern | eine Änderung, die Sie bestätigt haben und rückgängig machen können |
Jede Änderung wird Ihnen gezeigt, bevor sie angewendet wird: siehe Sicherheit durch Design.
Aktualisieren, entfernen, widerrufen
Abschnitt betitelt „Aktualisieren, entfernen, widerrufen“| Um | Tun Sie |
|---|---|
| Zu aktualisieren | uvx holt von Zeit zu Zeit selbst neue Versionen; erzwingen Sie es mit uvx --refresh avenir-mcp. Die Claude-Desktop-Erweiterung wird aktualisiert, indem Sie sie erneut herunterladen und auf dem Bildschirm Settings → Extensions über die bereits installierte Erweiterung ziehen |
| Zu entfernen | claude mcp remove avenir-mcp --scope user, oder löschen Sie den Eintrag avenir-mcp aus der Konfiguration des Clients. Die Erweiterung entfernen Sie unter Settings → Extensions, mitsamt dem Token |
| Aufzuräumen | Die einzige Datei von avenir-mcp auf Ihrem Rechner ist sein Journal, in ~/.local/state/avenir-mcp/ |
| Das Token zu widerrufen | YNAB → Account Settings → Developer Settings → Revoke neben dem Token |
- Ihr erstes Gespräch: eine geführte Tour.
- Funktionen: alles, was avenir-mcp kann.
- Konfiguration: jede Umgebungsvariable.
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