YNAB MCP Starter

Produktionsreifes TypeScript-Starter-Repository für einen schreibgeschützten YNAB MCP-Server.

Dieser Starter ist bewusst klein und explizit gehalten:

• Node.js 18+

• TypeScript mit strengen Compilereinstellungen

• Zod-validierte Tool-Eingaben und -Ausgaben

• Schreibgeschützter YNAB-API-Client mit Wiederholungsversuchen und Timeout-Handling

• Unit-Tests mit gemockten YNAB-Antworten

• Klare TODO-Markierungen, wo die MCP-Transportanbindung erfolgen sollte

Was dieses Repo enthält

src/
  clients/   YNAB API client, environment config, and error types
  schemas/   strict Zod schemas for tool contracts
  server/    MCP server composition and transport TODO placeholders
  tools/     read-only business logic for each YNAB capability
  types/     shared API and service types
tests/       unit tests with mocked API responses

Implementierte schreibgeschützte Funktionen:

• Budgets auflisten

• Konten auflisten

• Kategorien auflisten

• Letzte Transaktionen auflisten

• Nicht kategorisierte Transaktionen finden

• Monatliche Ausgaben nach Kategorie

Schreibzugriff ist absichtlich nicht implementiert.

Related MCP server: MCP Server Starter

Einrichtung

1. Abhängigkeiten installieren:

npm install

2. Die Beispiel-Umgebungsdatei kopieren:

cp .env.example .env

3. YNAB-Token in .env setzen:

YNAB_TOKEN=your-token-here

4. Lokalen Entwicklungsmodus ausführen:

npm run dev

Skripte

• npm run build kompiliert TypeScript nach dist/

• npm run dev führt den Starter-Einstiegspunkt mit Dateiüberwachung aus

• npm run lint führt ESLint aus

• npm run test führt Unit-Tests mit Vitest aus

• npm run typecheck führt TypeScript im No-Emit-Modus aus

MCP-Anbindung

Das Repo enthält die Server-Kompositionsschicht, legt Sie aber noch nicht auf einen Transport fest.

Achten Sie auf TODO-Kommentare in:

• src/server/index.ts

• src/server/registerTools.ts

Dort sollten Sie:

1. Den MCP-Server instanziieren

2. Tool-Definitionen und Schemas registrieren

3. stdio, SSE oder einen anderen Transport verbinden

4. Strukturiertes Logging und operative Hooks hinzufügen

Sicherheitshinweise

• Dieser Starter erwartet ein YNAB_TOKEN (persönliches Zugriffstoken) in den Umgebungsvariablen.

• Hardcodieren Sie das Token niemals in Quelldateien, Tests, Prompts oder Logs.

• Beschränken Sie das Token auf den schreibgeschützten operativen Gebrauch und rotieren Sie es, falls es offengelegt wurde.

• Vermeiden Sie das Logging von rohen YNAB-API-Antworten in der Produktion, da diese Transaktionsnotizen oder andere sensible Finanzmetadaten enthalten könnten.

• Dieser Starter führt nur GET-Anfragen an die YNAB-API durch. Es sind keine Schreib-Endpunkte implementiert.

Design-Hinweise

• Der YNAB-Client zentralisiert Wiederholungsversuche, Timeout-Handling und Fehler-Normalisierung.

• Tool-Module sind von HTTP-Details isoliert und arbeiten auf einer kleinen Service-Schnittstelle.

• Zod-Schemas validieren sowohl Tool-Eingaben als auch Tool-Ausgaben, um Abweichungen frühzeitig zu erkennen.

• Geldbeträge werden sowohl in YNAB-Millieinheiten als auch in menschenfreundlichen Dezimalbeträgen ausgegeben.

• Monatliche Kategorieausgaben zählen nur Abflüsse für den angeforderten Monat.

Beispiel-Prompts

• "List my YNAB budgets."

• "Show the accounts in budget budget-id-123."

• "List categories for budget budget-id-123."

• "Show the most recent 20 transactions in budget budget-id-123."

• "Find uncategorized transactions in budget budget-id-123 since 2026-04-01."

• "Summarize monthly spend by category for budget budget-id-123 in 2026-04."

Testen

Die Tests mocken YNAB-API-Antworten, sodass Sie das Verhalten ohne ein echtes Token validieren können:

npm run test

Ideen zur Produktionshärtung

• Hinzufügen von Request-Korrelations-IDs und strukturierten Logs

• Hinzufügen von Metriken zu Wiederholungsversuchen, Ratenbegrenzung und Latenz

• Hinzufügen von Integrationstests gegen eine gemockte HTTP-Schicht

• Hinzufügen von Ergebnis-Paginierungskontrollen, falls Ihr MCP-Client größere Ergebnismengen erwartet

• Hinzufügen einer Secrets-Manager-Integration anstelle von lokalen .env-Dateien für die Bereitstellung