ynab-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project State

An MCP server for YNAB (You Need A Budget). Implements the full read-only budget analysis surface (section A: ynab_get_user, ynab_list_budgets, ynab_get_budget, ynab_get_budget_settings, ynab_list_accounts, ynab_get_account, ynab_list_categories, ynab_get_category, ynab_list_months, ynab_get_month, ynab_list_payees, ynab_get_payee, ynab_list_scheduled_transactions, ynab_list_transactions, ynab_get_spending_summary), category management writes (section B: ynab_create_category_group, ynab_update_category_group, ynab_create_category, ynab_update_category, ynab_assign_budgeted_amount), and transaction management (section C: ynab_create_transaction, ynab_create_transactions_bulk, ynab_update_transaction, ynab_delete_transaction). ynab_delete_transaction is the reference implementation of the project's destructive-tool safety pattern: it requires confirm: z.literal(true), is annotated destructiveHint: true via the DELETES constant in src/tools/helpers.ts, and echoes the deleted transaction's fields back in the result. There is no ynab_delete_category — YNAB's public API has no delete endpoint for categories and no hidden field on the create/update request bodies, so a category can't be deleted or hidden through the API at all; this was verified directly against the ynab SDK's CategoriesApi/NewCategory/ExistingCategory types rather than assumed. ynab_create_category and ynab_update_category accept goal_target/goal_target_date/goal_needs_whole_amount to set a category's savings goal (setting goal_target on a category with no goal creates one), but the API's write models don't expose goal_type/goal_cadence/goal_day — those are read-only on CategoryBase and get chosen by YNAB (default NEED, or MF for Credit Card Payment categories) rather than settable directly. Account/budget setup (section D) is also implemented, minus ynab_close_account: ynab_create_account, ynab_create_payee, ynab_update_payee. There is no way to close, update, or delete an account through the API either — AccountsApi in the ynab SDK only exposes create/get/list, no update or close endpoint — so, like categories, an account can be created but never closed via this server once made; document this to the user before calling ynab_create_account. All four tool areas (read-only analysis, category management, transaction management, account/budget setup) are implemented. withYnabErrorHandling in src/tools/helpers.ts appends retry guidance to every error message based on YnabToolError.retryable (429s and network errors say to back off and retry later; everything else says retrying won't help); ynab_list_accounts, ynab_list_categories, ynab_list_months, ynab_list_payees, ynab_list_scheduled_transactions, and ynab_list_transactions all accept an optional last_knowledge_of_server input and return server_knowledge in their result for delta sync — YnabClient's list methods return ListResult<T> ({ items, serverKnowledge }, defined in src/ynab/client.ts) rather than a bare array, specifically to carry this cursor. The one remaining thing not yet done is a manual end-to-end pass through Claude Desktop against a real budget, which needs a human with a YNAB account — not something this agent can do itself. See README.md for setup instructions.