YNAB MCP

# YNAB Category Management Features This document describes the enhanced category management features added to the YNAB MCP integration. ## Features Added Two new powerful functions have been added to improve budget category management: 1. **Assign to Categories**: Allocate funds from Ready to Assign to multiple categories in a single operation 2. **Get Recommended Allocations**: Receive AI-powered recommendations for how to allocate available funds ## Usage ### Assign to Categories The `assign_to_categories` function allows you to distribute money from your "Ready to Assign" balance to multiple categories at once. This is especially useful when: - You've received new income and want to distribute it across several categories - You need to quickly fund multiple categories without making individual updates - You want to apply a budget template to multiple categories #### Parameters - `email`: Your YNAB account identifier (required) - `budgetId`: The budget ID (required) - `month`: The budget month in YYYY-MM format (required) - `categoryAllocations`: Array of category allocations, where each allocation has: - `categoryId`: The ID of the category to fund - `amount`: The amount to allocate (in dollars or milliunits) #### Example ```javascript { "email": "your.email@example.com", "budgetId": "your-budget-id", "month": "2025-04", "categoryAllocations": [ { "categoryId": "category-id-1", "amount": 50.00 // $50.00 }, { "categoryId": "category-id-2", "amount": 75.00 // $75.00 } ] } ``` ### Get Recommended Allocations The `get_recommended_allocations` function analyzes your budget patterns and goals to provide intelligent recommendations for allocating your available funds. Recommendations are prioritized based on: 1. **High Priority**: Underfunded goals and essential categories with negative balances 2. **Medium Priority**: Regular spending categories with insufficient funds 3. **Low Priority**: Savings goals and discretionary categories #### Parameters - `email`: Your YNAB account identifier (required) - `budgetId`: The budget ID (required) - `month`: The budget month in YYYY-MM format (required) - `availableAmount`: Optional override for the amount available to allocate #### Example ```javascript { "email": "your.email@example.com", "budgetId": "your-budget-id", "month": "2025-04" } ``` #### Response The response includes detailed recommendations with priority levels, reasoning, and suggested allocation amounts: ```javascript { "success": true, "month": "2025-04", "available_to_assign": 500000, // $500.00 "available_to_assign_formatted": "$500.00", "total_recommended": 450000, // $450.00 "total_recommended_formatted": "$450.00", "remaining_unallocated": 50000, // $50.00 "remaining_unallocated_formatted": "$50.00", "recommendations": [ { "category_id": "category-id-1", "category_name": "Rent/Mortgage", "group_name": "Immediate Obligations", "recommended_amount": 200000, "recommended_amount_formatted": "$200.00", "reason": "Underfunded goal (25% funded)", "priority": "high" }, { "category_id": "category-id-2", "category_name": "Groceries", "group_name": "Everyday Expenses", "recommended_amount": 150000, "recommended_amount_formatted": "$150.00", "reason": "Regular spending category with insufficient funds", "priority": "medium" }, { "category_id": "category-id-3", "category_name": "Vacation", "group_name": "Quality of Life Goals", "recommended_amount": 100000, "recommended_amount_formatted": "$100.00", "reason": "Savings/long-term goal", "priority": "low" } ] } ``` ## Implementation Details These features were implemented by: 1. Adding new API functions to the `categories.js` file: - `assignToCategories`: For distributing funds to specified categories - `getRecommendedAllocations`: For generating allocation recommendations 2. Updating the MCP handler to expose these functions externally 3. Adding appropriate schema definitions and tool documentation ## Benefits - **Time Savings**: Reduce the time spent on routine budget management tasks - **Consistency**: Apply consistent budgeting patterns across categories - **Intelligence**: Leverage AI-powered recommendations based on your spending patterns - **Automation**: Simplify the process of funding multiple categories at once