{ "name": "ynab-mcp", "version": "0.4.2", "tool_count": 69, "prompt_count": 7, "groups": [ { "id": "analytics", "label": "Analytics", "description": "Computed from your budget data: trends, health, forecasts and insights. All read-only.", "tools": [ "ynab_detect_recurring", "ynab_spending_analysis", "ynab_budget_health", "ynab_savings_opportunities", "ynab_budget_vs_actuals", "ynab_quick_summary", "ynab_income_expense", "ynab_net_worth", "ynab_goal_progress", "ynab_spending_by_payee", "ynab_unused_categories", "ynab_monthly_comparison", "ynab_spending_trends", "ynab_cash_flow_forecast", "ynab_reconciliation_helper", "ynab_budget_suggestions", "ynab_overspending_alerts", "ynab_transaction_search", "ynab_spending_pace", "ynab_category_balances", "ynab_credit_card_status", "ynab_age_of_money", "ynab_preview_scheduled_transaction" ] }, { "id": "budgets", "label": "Budgets", "description": "Budgets and their settings.", "tools": [ "ynab_list_budgets", "ynab_get_budget", "ynab_get_budget_settings" ] }, { "id": "accounts", "label": "Accounts", "description": "Bank, credit and tracking accounts with balances.", "tools": [ "ynab_list_accounts", "ynab_get_account", "ynab_create_account" ] }, { "id": "categories", "label": "Categories", "description": "Category groups, categories, monthly budgeted amounts and targets.", "tools": [ "ynab_list_categories", "ynab_get_category", "ynab_get_month_category", "ynab_update_category", "ynab_move_money", "ynab_update_category_details", "ynab_create_category", "ynab_create_category_group", "ynab_update_category_group" ] }, { "id": "transactions", "label": "Transactions", "description": "Find, add, change and remove transactions, including splits.", "tools": [ "ynab_list_transactions", "ynab_get_transaction", "ynab_create_transaction", "ynab_update_transaction", "ynab_delete_transaction", "ynab_create_transactions", "ynab_update_transactions", "ynab_list_account_transactions", "ynab_list_category_transactions", "ynab_list_payee_transactions", "ynab_import_transactions" ] }, { "id": "scheduled-transactions", "label": "Scheduled transactions", "description": "Recurring bills, subscriptions and future-dated transactions.", "tools": [ "ynab_list_scheduled_transactions", "ynab_get_scheduled_transaction", "ynab_create_scheduled_transaction", "ynab_update_scheduled_transaction", "ynab_delete_scheduled_transaction" ] }, { "id": "payees", "label": "Payees", "description": "Payees (merchants and people) and their saved locations.", "tools": [ "ynab_list_payees", "ynab_get_payee", "ynab_create_payee", "ynab_update_payee", "ynab_list_payee_locations", "ynab_get_payee_location", "ynab_list_payee_locations_by_payee" ] }, { "id": "months", "label": "Months", "description": "Month-by-month budget summaries.", "tools": [ "ynab_list_months", "ynab_get_month" ] }, { "id": "money-movements", "label": "Money movements", "description": "Moves of money between categories made in YNAB.", "tools": [ "ynab_list_money_movements", "ynab_list_money_movement_groups" ] }, { "id": "user", "label": "User", "description": "The signed-in YNAB user.", "tools": [ "ynab_get_user" ] }, { "id": "system", "label": "System", "description": "The server's own state: rate limit, audit log and a health check.", "tools": [ "ynab_rate_limit_status", "ynab_audit_log", "ynab_health_check" ] } ], "tools": [ { "name": "ynab_get_user", "title": "Get User", "group": "user", "kind": "read", "deprecated": false, "summary": "Get information about the authenticated YNAB user.", "asks": [ "Who am I logged in as?", "What's my YNAB user ID?", "Show my user ID" ], "notes": "Returns the user's ID.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [] }, { "name": "ynab_list_budgets", "title": "List Budgets", "group": "budgets", "kind": "read", "deprecated": false, "summary": "List all budgets the user has access to in YNAB.", "asks": [ "What budgets do I have?", "Show me my YNAB budgets", "List my budgets", "Which budget should I use?" ], "notes": "Returns budget names, IDs, last modified dates, first and last month, and date format. Optionally includes account summaries.\n\nNot possible through the YNAB API (do it in the YNAB app): creating, renaming or deleting plans (budgets), and changing plan settings.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "include_accounts", "type": "boolean", "required": false, "description": "Whether to include account summaries for each budget" } ] }, { "name": "ynab_get_budget", "title": "Get Budget", "group": "budgets", "kind": "read", "deprecated": false, "summary": "Get detailed information about a specific budget including accounts, categories, and payees.", "asks": [ "Show me my budget details", "What's in my budget?", "Give me an overview of my budget", "Tell me about my main budget" ], "notes": "Returns comprehensive budget data including all accounts, category groups, categories, and payees.\n\nNot possible through the YNAB API (do it in the YNAB app): creating, renaming or deleting plans (budgets), and changing plan settings.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_get_budget_settings", "title": "Get Budget Settings", "group": "budgets", "kind": "read", "deprecated": false, "summary": "Get settings for a budget including currency format, date format, and other preferences.", "asks": [ "What currency is my budget in?", "Show my budget settings", "What's my budget date format?", "What are my YNAB preferences?" ], "notes": "Returns currency format, date format, and currency ISO code.\n\nNot possible through the YNAB API (do it in the YNAB app): creating, renaming or deleting plans (budgets), and changing plan settings such as currency or date format.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_list_accounts", "title": "List Accounts", "group": "accounts", "kind": "read", "deprecated": false, "summary": "List all accounts in a budget with their current balances.", "asks": [ "What accounts do I have?", "Show my account balances", "What's my net worth?", "List my bank accounts", "How much money do I have?" ], "notes": "Returns account names, types, and current/cleared/uncleared balances, plus on_budget, closed, note, last_reconciled_at, direct import status, transfer_payee_id (use it as payee_id to record a transfer), and debt details (original balance, interest rates, minimum payments, escrow) when present.\nPass since_server_knowledge (the server_knowledge of an earlier response) to get only the accounts changed since then.\n\nNot possible through the YNAB API (do it in the YNAB app): editing, closing or reopening accounts, setting up loan accounts, and changing interest rates.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "include_closed", "type": "boolean", "required": false, "description": "Whether to include closed accounts" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_get_account", "title": "Get Account", "group": "accounts", "kind": "read", "deprecated": false, "summary": "Get details about a specific account including balance and recent activity.", "asks": [ "Show me details for my checking account", "What's the balance of [account name]?", "Tell me about my savings account", "Get info on a specific account" ], "notes": "Also returns transfer_payee_id: set it as payee_id on ynab_create_transaction to record a transfer into this account.\n\nRequires an account_id. Use ynab_list_accounts first to find the account ID.\n\nNot possible through the YNAB API (do it in the YNAB app): editing, closing or reopening an account, setting up loan accounts, and changing interest rates.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "account_id", "type": "string", "required": true, "description": "The account UUID to retrieve" } ] }, { "name": "ynab_create_account", "title": "Create Account", "group": "accounts", "kind": "write", "deprecated": false, "summary": "Create a new account in a budget.", "asks": [ "Add a new checking account", "Create a savings account", "I want to add my credit card to YNAB", "Set up a new account with balance X" ], "notes": "Account types (only these can be created via the YNAB API): checking, savings, cash, creditCard, otherAsset, otherLiability\n\nBalance should be provided in dollars (e.g., 1000.50). For credit cards and liability accounts, use a negative balance for amounts owed.\n\nNot possible through the YNAB API (do it in the YNAB app): editing, closing or reopening accounts, setting up loan accounts, and changing interest rates.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "name", "type": "string", "required": true, "description": "The name of the account" }, { "name": "type", "type": "\"checking\" | \"savings\" | \"cash\" | \"creditCard\" | \"otherAsset\" | \"otherLiability\"", "required": true, "description": "The type of account" }, { "name": "balance", "type": "number", "required": true, "description": "The starting balance in dollars (e.g., 1000.50)" } ] }, { "name": "ynab_list_categories", "title": "List Categories", "group": "categories", "kind": "read", "deprecated": false, "summary": "List all category groups and categories in a budget with budgeted amounts and balances.", "asks": [ "What categories do I have?", "Show my budget categories", "How is my budget organized?", "What are my spending categories?", "List my budget breakdown" ], "notes": "Returns category groups with their categories, including budgeted amounts, activity, and remaining balances.\nPass since_server_knowledge (the server_knowledge of an earlier response) to get only the groups and categories changed since then. Budgeted, activity and balance are for the current month, and a new month changes them without YNAB reporting a change, so re-read in full after a month begins.\n\nNot possible through the YNAB API (do it in the YNAB app): target cadences other than monthly/weekly/yearly, due days, choosing the target type, and snoozing a target; hiding, unhiding, deleting or reordering categories and groups.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "include_hidden", "type": "boolean", "required": false, "description": "Whether to include hidden categories" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_get_category", "title": "Get Category", "group": "categories", "kind": "read", "deprecated": false, "summary": "Get details about a specific budget category including budgeted amount, activity, and goal status.", "asks": [ "Show me details for my Groceries category", "What's the balance in [category name]?", "How much is budgeted for [category]?", "What's my goal progress for [category]?" ], "notes": "Requires a category_id. Use ynab_list_categories first to find the category ID.\n\nNot possible through the YNAB API (do it in the YNAB app): target cadences other than monthly/weekly/yearly, due days, choosing the target type, and snoozing a target.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "category_id", "type": "string", "required": true, "description": "The category UUID to retrieve" } ] }, { "name": "ynab_get_month_category", "title": "Get Month Category", "group": "categories", "kind": "read", "deprecated": false, "summary": "Get category details for a specific month, including that month's budgeted amount, activity, and balance.", "asks": [ "How much did I budget for Groceries in January?", "What was my spending in [category] last month?", "Show me [category] for [month]", "What was my [category] balance in [month]?" ], "notes": "Use first-of-month format for the month parameter (e.g., 2024-01-01 for January 2024).\nRequires a category_id. Use ynab_list_categories first to find the category ID.\n\nNot possible through the YNAB API (do it in the YNAB app): target cadences other than monthly/weekly/yearly, due days, choosing the target type, and snoozing a target.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": true, "description": "The budget month in YYYY-MM-01 format (first of month)" }, { "name": "category_id", "type": "string", "required": true, "description": "The category UUID to retrieve" } ] }, { "name": "ynab_update_category", "title": "Update Category Budget", "group": "categories", "kind": "destructive", "deprecated": false, "summary": "Update the budgeted amount for a category in a specific month.", "asks": [ "Budget $500 for Groceries this month", "Set my dining out budget to $200", "Increase my entertainment budget", "Change the budget for [category] to [amount]" ], "notes": "To rename a category, change its note, move it to another group, or set/clear its target, use ynab_update_category_details instead (this tool only changes a month's budgeted amount).\n\nUse first-of-month format for the month parameter (e.g., 2024-01-01 for January 2024).\nThe budgeted amount is in dollars (e.g., 500.00 for $500).\nRequires a category_id. Use ynab_list_categories first to find the category ID.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": true, "description": "The budget month in YYYY-MM-01 format (first of month)" }, { "name": "category_id", "type": "string", "required": true, "description": "The category UUID to update" }, { "name": "budgeted", "type": "number", "required": true, "description": "The new budgeted amount in dollars" } ] }, { "name": "ynab_move_money", "title": "Move Money Between Categories", "group": "categories", "kind": "destructive", "deprecated": false, "summary": "Move budgeted money from one category to another within a single month.", "asks": [ "Move $50 from Dining Out to Groceries", "Cover my overspent Groceries category from Fun Money", "Shift $100 of this month's budget from [category] to [category]" ], "notes": "This subtracts the amount from the first category's budgeted amount and adds it to the second's, for the given month. It changes budgeted amounts only: it does NOT create a YNAB money-movement record, because the YNAB API has no money-movement write, so the move will not appear in ynab_list_money_movements. The two updates are not atomic: if the second fails, the tool tries to restore the first and reports whether that rollback succeeded. A failed move may need a manual check: if a request errors with an unknown outcome, or the source category was edited by someone else in the meantime, the tool does not guess and reports move_outcome_uncertain or move_partially_applied, and the categories should be verified with ynab_get_month_category.\n\nThe amount is in dollars and must be greater than zero. The month is \"current\" or first-of-month format (e.g., 2024-01-01). Use ynab_list_categories to find category IDs. To set an absolute budgeted amount for one category use ynab_update_category.\n\nInternal categories (such as \"Inflow: Ready to Assign\") cannot be used as the source or target. To assign money from Ready to Assign to a category, set that category's budgeted amount with ynab_update_category.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": true, "description": "The budget month: \"current\" or first-of-month YYYY-MM-01" }, { "name": "from_category_id", "type": "string", "required": true, "description": "The category UUID to take budgeted money from" }, { "name": "to_category_id", "type": "string", "required": true, "description": "The category UUID to add budgeted money to (must differ from from_category_id)" }, { "name": "amount", "type": "number", "required": true, "description": "Amount to move in dollars (greater than zero)" } ] }, { "name": "ynab_update_category_details", "title": "Update Category Details", "group": "categories", "kind": "destructive", "deprecated": false, "summary": "Update a category's details: rename it, change its note, move it to a different category group, or set/clear its target (goal).", "asks": [ "Rename my [category] category to X", "Add a note to [category]\" or \"Clear the note on [category]", "Move [category] to the [group] group", "Set a $200 monthly target on [category]\" or \"Remove the target from [category]" ], "notes": "- \"Set a $50 weekly target for Dining Out\" (goal_target 50 + goal_frequency \"weekly\")\n\nProvide at least one of name, note, category_group_id, goal_target (in dollars, e.g. 200 for $200), goal_target_date, goal_needs_whole_amount, goal_frequency (monthly|weekly|yearly; recurring target, requires goal_target, not combinable with goal_target_date). Target fields accept null to remove the existing value; note accepts null or \"\" to clear it. Moving into YNAB's internal category group is rejected.\n\nRequires a category_id (and a category_group_id when moving). Use ynab_list_categories first to find the IDs.\n\nTo change how much is budgeted for a category in a given month, use ynab_update_category instead; this tool never changes budgeted amounts.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.\n\nNot possible through the YNAB API (do it in the YNAB app): target cadences other than monthly/weekly/yearly, due days, choosing the target type, snoozing, and hiding, unhiding, deleting or reordering categories.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "category_id", "type": "string", "required": true, "description": "The category UUID to update" }, { "name": "name", "type": "string", "required": false, "description": "New name for the category" }, { "name": "note", "type": "string | null", "required": false, "description": "New note for the category. Pass null or an empty string to clear the note" }, { "name": "category_group_id", "type": "string", "required": false, "description": "UUID of the category group to move the category into" }, { "name": "goal_target", "type": "number | null", "required": false, "description": "Target amount in dollars (e.g. 200 for $200.00; >= 0). Creates a monthly goal if none exists Pass null to remove the existing value." }, { "name": "goal_target_date", "type": "string | null", "required": false, "description": "Target date in YYYY-MM-DD format. Not supported for categories paired to a loan account Pass null to remove the existing value." }, { "name": "goal_needs_whole_amount", "type": "boolean | null", "required": false, "description": "Only for spending-target (NEED) goals. true = \"Set aside another...\" each period, false = \"Refill up to...\" Pass null to remove the existing value." }, { "name": "goal_frequency", "type": "\"monthly\" | \"weekly\" | \"yearly\"", "required": false, "description": "Makes goal_target a recurring \"set aside\" (NEED) target that repeats at this frequency, e.g. goal_target 50 with \"weekly\" = $50 every week. Replaces any existing target. Requires goal_target; cannot be combined with goal_target_date; not supported for Credit Card Payment categories or categories paired to a loan account" } ] }, { "name": "ynab_create_category", "title": "Create Category", "group": "categories", "kind": "write", "deprecated": false, "summary": "Create a new category inside an existing category group.", "asks": [ "Add a new category called X to my [group] group", "Create a budgeting category for Y" ], "notes": "Requires a category_group_id. Use ynab_list_categories first to find the group ID.\n\nOptionally set a target (goal) at creation: goal_target (in dollars, e.g. 200 for $200), goal_target_date (YYYY-MM-DD) and goal_needs_whole_amount. Supplying goal_target creates a monthly spending target. Add goal_frequency (monthly, weekly or yearly) with goal_target for a recurring \"set aside\" target (e.g. \"Create Dining Out with a $50 weekly target\" = goal_target 50, goal_frequency weekly); it cannot be combined with goal_target_date.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.\n\nNot possible through the YNAB API (do it in the YNAB app): hiding, unhiding, deleting or reordering categories, target cadences other than monthly/weekly/yearly, due days, choosing the target type, and snoozing a target.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "category_group_id", "type": "string", "required": true, "description": "The UUID of the category group to add the category to" }, { "name": "name", "type": "string", "required": true, "description": "The name of the new category" }, { "name": "note", "type": "string", "required": false, "description": "Optional note for the category" }, { "name": "goal_target", "type": "number", "required": false, "description": "Target amount in dollars (e.g. 200 for $200.00; >= 0). Creates a monthly goal if none exists" }, { "name": "goal_target_date", "type": "string", "required": false, "description": "Target date in YYYY-MM-DD format. Not supported for categories paired to a loan account" }, { "name": "goal_needs_whole_amount", "type": "boolean", "required": false, "description": "Only for spending-target (NEED) goals. true = \"Set aside another...\" each period, false = \"Refill up to...\"" }, { "name": "goal_frequency", "type": "\"monthly\" | \"weekly\" | \"yearly\"", "required": false, "description": "Makes goal_target a recurring \"set aside\" (NEED) target that repeats at this frequency, e.g. goal_target 50 with \"weekly\" = $50 every week. Replaces any existing target. Requires goal_target; cannot be combined with goal_target_date; not supported for Credit Card Payment categories or categories paired to a loan account" } ] }, { "name": "ynab_create_category_group", "title": "Create Category Group", "group": "categories", "kind": "write", "deprecated": false, "summary": "Create a new category group.", "asks": [ "Add a new category group called X", "Create a top-level budgeting section for Y" ], "notes": "Category groups organize related categories (e.g., \"Monthly Bills\", \"Fun Money\").\nAfter creating a group, use ynab_create_category to add categories to it.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.\n\nNot possible through the YNAB API (do it in the YNAB app): hiding, unhiding, deleting or reordering category groups.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "name", "type": "string", "required": true, "description": "The name of the new category group" } ] }, { "name": "ynab_update_category_group", "title": "Rename Category Group", "group": "categories", "kind": "destructive", "deprecated": false, "summary": "Rename an existing category group.", "asks": [ "Rename the [group] category group", "Change the name of my budgeting section" ], "notes": "Requires a category_group_id. Use ynab_list_categories first to find the group ID.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.\n\nNot possible through the YNAB API (do it in the YNAB app): hiding, unhiding, deleting or reordering category groups.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "category_group_id", "type": "string", "required": true, "description": "The category group UUID to update" }, { "name": "name", "type": "string", "required": true, "description": "The new name for the category group" } ] }, { "name": "ynab_list_payees", "title": "List Payees", "group": "payees", "kind": "read", "deprecated": false, "summary": "List all payees in a budget.", "asks": [ "Show my payees", "List all merchants", "Who have I paid?", "Find a payee" ], "notes": "Returns payee names and IDs. Payees are merchants, people, or places you transact with.\nPass since_server_knowledge (the server_knowledge of an earlier response) to get only the payees changed since then.\n\nNot possible through the YNAB API (do it in the YNAB app): deleting or merging payees, and editing payee locations.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_get_payee", "title": "Get Payee", "group": "payees", "kind": "read", "deprecated": false, "summary": "Get details about a specific payee.", "asks": [ "Show me details for [payee]", "Get info on a merchant" ], "notes": "Requires a payee_id. Use ynab_list_payees first to find the payee ID.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "payee_id", "type": "string", "required": true, "description": "The payee UUID to retrieve" } ] }, { "name": "ynab_create_payee", "title": "Create Payee", "group": "payees", "kind": "write", "deprecated": false, "summary": "Create a new payee.", "asks": [ "Add a payee called X", "Create a new merchant" ], "notes": "Most of the time payees are created automatically when you add a transaction with a\nnew payee_name. Use this tool when you need a payee to exist ahead of time.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.\n\nNot possible through the YNAB API (do it in the YNAB app): deleting or merging payees, and editing payee locations.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "name", "type": "string", "required": true, "description": "The name of the new payee" } ] }, { "name": "ynab_update_payee", "title": "Rename Payee", "group": "payees", "kind": "destructive", "deprecated": false, "summary": "Rename an existing payee.", "asks": [ "Rename payee X to Y", "Fix the name of this payee", "Clean up this merchant name" ], "notes": "Requires a payee_id. Use ynab_list_payees first to find the payee ID.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.\n\nNot possible through the YNAB API (do it in the YNAB app): deleting or merging payees, and editing payee locations.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "payee_id", "type": "string", "required": true, "description": "The payee UUID to update" }, { "name": "name", "type": "string", "required": true, "description": "The new name for the payee" } ] }, { "name": "ynab_list_payee_locations", "title": "List Payee Locations", "group": "payees", "kind": "read", "deprecated": false, "summary": "List all payee locations for a budget.", "asks": [ "Where are my payees located?", "Show payee locations", "Map of where I spend", "Payee geographic data" ], "notes": "Returns payee locations with latitude/longitude for mapping purposes.\n\nNot possible through the YNAB API (do it in the YNAB app): adding, editing or deleting payee locations.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_get_payee_location", "title": "Get Payee Location", "group": "payees", "kind": "read", "deprecated": false, "summary": "Get a specific payee location by ID.", "asks": [], "notes": "Returns the details of a single payee location including coordinates.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "payee_location_id", "type": "string", "required": true, "description": "The payee location UUID" } ] }, { "name": "ynab_list_payee_locations_by_payee", "title": "List Locations for Payee", "group": "payees", "kind": "read", "deprecated": false, "summary": "List all locations for a specific payee.", "asks": [ "Where is [payee] located?", "Show locations for [store]", "Which [payee] locations have I visited?" ], "notes": "Returns all recorded locations for a specific payee.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "payee_id", "type": "string", "required": true, "description": "The payee UUID" } ] }, { "name": "ynab_list_months", "title": "List Budget Months", "group": "months", "kind": "read", "deprecated": false, "summary": "List all budget months with summary information.", "asks": [ "Show my budget months", "What months do I have budgeted?", "List my budget history", "Show me past months" ], "notes": "Returns each month's income, budgeted, activity, and to-be-budgeted amounts.\nPass since_server_knowledge (the server_knowledge of an earlier response) to get only the months changed since then.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_get_month", "title": "Get Budget Month", "group": "months", "kind": "read", "deprecated": false, "summary": "Get detailed information about a specific budget month including all categories.", "asks": [ "Show me January's budget", "What did I budget last month?", "Give me details for [month]", "How much did I have to budget in [month]?" ], "notes": "Use first-of-month format for the month parameter (e.g., 2024-01-01 for January 2024).\nUse \"current\" for the current month.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": true, "description": "The budget month in YYYY-MM-DD format (use first of month, or \"current\")" } ] }, { "name": "ynab_list_transactions", "title": "List Transactions", "group": "transactions", "kind": "read", "deprecated": false, "summary": "List transactions for a budget with optional filters.", "asks": [ "Show my recent transactions", "What did I spend this month?", "List my uncategorized transactions", "Show transactions since [date]", "What purchases have I made recently?", "Show me the past 7 days of transactions", "What did I spend last week?" ], "notes": "- \"Show all transactions for March\" (month: \"2024-03-01\")\n\nSupports filtering by date (ISO or natural language like \"past 30 days\", \"this month\") and type (uncategorized/unapproved).\nReturns transaction details including date, payee, amount, category, and status.\n\nNOTE: If since_date is omitted, YNAB returns only the last 12 months of transactions (API 1.85 default). Pass an earlier since_date to see older history. until_date sets an inclusive upper bound.\nPass month (YYYY-MM-01 or \"current\") to list a single budget month instead of the default 12-month window; it can be narrowed further with since_date/until_date.\nPass since_server_knowledge (the server_knowledge of an earlier response with the same filters) to get only the transactions changed since then. If more changed than limit, the response keeps your cursor (cursor_withheld: true) so nothing is skipped. A delta may leave out a transaction that changed so it no longer matches the filters; re-read in full to keep a filtered list exact.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": false, "description": "Only return transactions in this budget month: YYYY-MM-01 (first of month) or \"current\". Pending transactions are excluded. May be combined with since_date/until_date to narrow within the month" }, { "name": "since_date", "type": "string", "required": false, "description": "Only return transactions on or after this date. Accepts YYYY-MM-DD or natural language: \"today\", \"this week\", \"past 30 days\", etc.. If omitted, YNAB returns only the last 12 months; pass an earlier date for older history" }, { "name": "type", "type": "\"uncategorized\" | \"unapproved\"", "required": false, "description": "Filter by transaction type: \"uncategorized\" or \"unapproved\"" }, { "name": "until_date", "type": "string", "required": false, "description": "Only return transactions on or before this date (inclusive). Accepts YYYY-MM-DD or \"today\" or \"yesterday\". Prefer ISO dates for an end bound: period names such as \"last month\" or \"this year\" resolve to the START of that period, so they would exclude most of it" }, { "name": "limit", "type": "number", "required": false, "description": "Maximum number of transactions to return (default 100, max 500)" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_get_transaction", "title": "Get Transaction", "group": "transactions", "kind": "read", "deprecated": false, "summary": "Get details about a specific transaction.", "asks": [ "Show me details for that transaction", "What's the info on transaction [id]?", "Tell me more about that purchase" ], "notes": "Requires a transaction_id. Use ynab_list_transactions first to find the transaction ID.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "transaction_id", "type": "string", "required": true, "description": "The transaction UUID to retrieve" } ] }, { "name": "ynab_create_transaction", "title": "Create Transaction", "group": "transactions", "kind": "write", "deprecated": false, "summary": "Create a new transaction in a budget.", "asks": [ "Add a transaction for $50 at Amazon", "Record a purchase", "Log an expense", "Create a transaction", "Split this $100 purchase between groceries and household" ], "notes": "Requires READ_ONLY mode to be disabled (YNAB_READ_ONLY=false).\nAmount should be negative for expenses/outflows and positive for income/inflows.\n\nSplit transactions: pass subtransactions (at least 2, each with amount in dollars and optional payee_id/payee_name, category_id, memo). Split amounts must sum exactly to the parent amount, and the parent must not set category_id. The splits of an existing transaction cannot be edited afterwards (YNAB limitation), so get them right on creation.\nPass import_id to make the create idempotent: the request is sent in YNAB's skip-duplicates form, so if that import_id already exists nothing is created and the result has success=false with duplicate_import_ids.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "account_id", "type": "string", "required": true, "description": "The account UUID for this transaction" }, { "name": "date", "type": "string", "required": true, "description": "Transaction date in YYYY-MM-DD format" }, { "name": "amount", "type": "number", "required": true, "description": "Amount in dollars (negative for outflow, positive for inflow)" }, { "name": "payee_id", "type": "string", "required": false, "description": "Payee UUID" }, { "name": "payee_name", "type": "string", "required": false, "description": "Payee name (creates new payee if payee_id not provided)" }, { "name": "category_id", "type": "string", "required": false, "description": "Category UUID" }, { "name": "memo", "type": "string", "required": false, "description": "Transaction memo/note" }, { "name": "cleared", "type": "\"cleared\" | \"uncleared\" | \"reconciled\"", "required": false, "description": "Cleared status" }, { "name": "approved", "type": "boolean", "required": false, "description": "Whether the transaction is approved" }, { "name": "flag_color", "type": "\"red\" | \"orange\" | \"yellow\" | \"green\" | \"blue\" | \"purple\"", "required": false, "description": "Flag color" }, { "name": "import_id", "type": "string", "required": false, "description": "Unique import ID for deduplication (max 36 chars)" }, { "name": "subtransactions", "type": "array of object", "required": false, "description": "Split the transaction across categories (at least 2). Split amounts (dollars) must sum exactly to the parent amount, and the parent must not set category_id. Each split takes amount, optional payee_id or payee_name, category_id and memo." } ] }, { "name": "ynab_update_transaction", "title": "Update Transaction", "group": "transactions", "kind": "destructive", "deprecated": false, "summary": "Update an existing transaction.", "asks": [ "Change the category on that transaction", "Update the amount", "Mark transaction as cleared", "Add a memo to the transaction", "Recategorize a transaction", "Uncategorize that transaction\" / \"Remove the memo\" / \"Clear the payee" ], "notes": "Requires READ_ONLY mode to be disabled (YNAB_READ_ONLY=false).\nOnly provide the fields you want to change; omitted fields stay unchanged.\nTo clear a field, pass null (distinct from omitting it): category_id null uncategorizes the transaction, payee_id null clears the payee, memo null clears the memo.\nSplit limitation: YNAB cannot edit the splits of an existing transaction, so you cannot change, add or remove splits here. To restructure splits, delete the transaction and create a new one with subtransactions via ynab_create_transaction.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "transaction_id", "type": "string", "required": true, "description": "The transaction UUID to update" }, { "name": "account_id", "type": "string", "required": false, "description": "New account UUID" }, { "name": "date", "type": "string", "required": false, "description": "New transaction date in YYYY-MM-DD format" }, { "name": "amount", "type": "number", "required": false, "description": "New amount in dollars" }, { "name": "payee_id", "type": "string | null", "required": false, "description": "New payee UUID (null to clear the payee)" }, { "name": "payee_name", "type": "string", "required": false, "description": "New payee name" }, { "name": "category_id", "type": "string | null", "required": false, "description": "New category UUID (null to uncategorize)" }, { "name": "memo", "type": "string | null", "required": false, "description": "New memo/note (null to clear the memo)" }, { "name": "cleared", "type": "\"cleared\" | \"uncleared\" | \"reconciled\"", "required": false, "description": "New cleared status" }, { "name": "approved", "type": "boolean", "required": false, "description": "New approved status" }, { "name": "flag_color", "type": "\"red\" | \"orange\" | \"yellow\" | \"green\" | \"blue\" | \"purple\" | null", "required": false, "description": "New flag color (null to remove)" } ] }, { "name": "ynab_delete_transaction", "title": "Delete Transaction", "group": "transactions", "kind": "destructive", "deprecated": false, "summary": "Delete a transaction from a budget.", "asks": [ "Delete that transaction", "Remove the transaction", "Cancel that purchase entry" ], "notes": "Requires READ_ONLY mode to be disabled (YNAB_READ_ONLY=false).\nThis action cannot be undone.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "transaction_id", "type": "string", "required": true, "description": "The transaction UUID to delete" } ] }, { "name": "ynab_create_transactions", "title": "Create Transactions in Bulk", "group": "transactions", "kind": "write", "deprecated": false, "summary": "Create multiple transactions in a single request (bulk import).", "asks": [ "Import these transactions", "Add multiple transactions", "Bulk create transactions", "Import these transactions, one of them split across categories" ], "notes": "Requires READ_ONLY mode to be disabled (YNAB_READ_ONLY=false).\nMaximum 100 transactions per request.\nUse import_id to prevent duplicate imports.\nAny item may carry subtransactions (at least 2, amounts in dollars) to create a split transaction: split amounts must sum exactly to that item's amount, and the item must not set category_id. YNAB cannot edit the splits of an existing transaction afterwards.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "transactions", "type": "array of object", "required": true, "description": "Array of transactions to create" } ] }, { "name": "ynab_update_transactions", "title": "Update Transactions in Bulk", "group": "transactions", "kind": "destructive", "deprecated": false, "summary": "Update multiple existing transactions in a single request (up to 100).", "asks": [ "Recategorize all these transactions", "Mark these transactions as cleared", "Approve all imported transactions" ], "notes": "Each entry must include exactly one of id or import_id to address the transaction. Use ynab_list_transactions first to find ids.\nAmounts are in dollars (e.g., -42.50 for a $42.50 outflow).\nTo clear a field, pass null (distinct from omitting it, which leaves it unchanged): category_id null uncategorizes, payee_id null clears the payee, memo null clears the memo.\nYNAB cannot edit the splits of an existing transaction.\n\n**Note:** This is a write operation. Requires YNAB_READ_ONLY=false.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "transactions", "type": "array of object", "required": true, "description": "Array of transactions to update (1-100). Each must include exactly one of id or import_id." } ] }, { "name": "ynab_list_account_transactions", "title": "List Account Transactions", "group": "transactions", "kind": "read", "deprecated": false, "summary": "List transactions for a specific account.", "asks": [ "Show transactions for my checking account", "What purchases were made on my credit card?", "List activity in [account name]", "Which transactions in my checking account are unapproved?", "Show uncategorized transactions in [account name]" ], "notes": "Pass type (\"unapproved\" or \"uncategorized\") to narrow to transactions that need attention.\nRequires an account_id. Use ynab_list_accounts first to find the account ID.\n\nNOTE: If since_date is omitted, YNAB returns only the last 12 months of transactions (API 1.85 default). Pass an earlier since_date to see older history. until_date sets an inclusive upper bound.\nPass since_server_knowledge (the server_knowledge of an earlier response with the same filters) to get only the transactions changed since then. If more changed than limit, the response keeps your cursor (cursor_withheld: true) so nothing is skipped. A delta may leave out a transaction that changed so it no longer matches the filters; re-read in full to keep a filtered list exact.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "account_id", "type": "string", "required": true, "description": "The account UUID to get transactions for" }, { "name": "since_date", "type": "string", "required": false, "description": "Only return transactions on or after this date. Accepts YYYY-MM-DD or natural language like \"past 30 days\". If omitted, YNAB returns only the last 12 months; pass an earlier date for older history" }, { "name": "until_date", "type": "string", "required": false, "description": "Only return transactions on or before this date (inclusive). Accepts YYYY-MM-DD or \"today\" or \"yesterday\". Prefer ISO dates for an end bound: period names such as \"last month\" or \"this year\" resolve to the START of that period, so they would exclude most of it" }, { "name": "type", "type": "\"uncategorized\" | \"unapproved\"", "required": false, "description": "Filter by transaction type: \"uncategorized\" or \"unapproved\"" }, { "name": "limit", "type": "number", "required": false, "description": "Maximum number of transactions to return (default 100, max 500)" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_list_category_transactions", "title": "List Category Transactions", "group": "transactions", "kind": "read", "deprecated": false, "summary": "List transactions for a specific category.", "asks": [ "Show my grocery transactions", "What did I spend on dining out?", "List transactions in [category name]", "Show unapproved transactions in the [category] category" ], "notes": "Pass type (\"unapproved\" or \"uncategorized\") to narrow to transactions that need attention.\nRequires a category_id. Use ynab_list_categories first to find the category ID.\n\nNOTE: If since_date is omitted, YNAB returns only the last 12 months of transactions (API 1.85 default). Pass an earlier since_date to see older history. until_date sets an inclusive upper bound.\nPass since_server_knowledge (the server_knowledge of an earlier response with the same filters) to get only the transactions changed since then. If more changed than limit, the response keeps your cursor (cursor_withheld: true) so nothing is skipped. A delta may leave out a transaction that changed so it no longer matches the filters; re-read in full to keep a filtered list exact.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "category_id", "type": "string", "required": true, "description": "The category UUID to get transactions for" }, { "name": "since_date", "type": "string", "required": false, "description": "Only return transactions on or after this date. Accepts YYYY-MM-DD or natural language like \"past 30 days\". If omitted, YNAB returns only the last 12 months; pass an earlier date for older history" }, { "name": "until_date", "type": "string", "required": false, "description": "Only return transactions on or before this date (inclusive). Accepts YYYY-MM-DD or \"today\" or \"yesterday\". Prefer ISO dates for an end bound: period names such as \"last month\" or \"this year\" resolve to the START of that period, so they would exclude most of it" }, { "name": "type", "type": "\"uncategorized\" | \"unapproved\"", "required": false, "description": "Filter by transaction type: \"uncategorized\" or \"unapproved\"" }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of transactions to return (default 100, max 500)" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_list_payee_transactions", "title": "List Payee Transactions", "group": "transactions", "kind": "read", "deprecated": false, "summary": "List transactions for a specific payee (merchant/vendor).", "asks": [ "Show my Amazon purchases", "What have I spent at Costco?", "List transactions for [payee name]", "Are there unapproved transactions for [payee]?" ], "notes": "Pass type (\"unapproved\" or \"uncategorized\") to narrow to transactions that need attention.\nRequires a payee_id. Use ynab_list_payees first to find the payee ID.\n\nNOTE: If since_date is omitted, YNAB returns only the last 12 months of transactions (API 1.85 default). Pass an earlier since_date to see older history. until_date sets an inclusive upper bound.\nPass since_server_knowledge (the server_knowledge of an earlier response with the same filters) to get only the transactions changed since then. If more changed than limit, the response keeps your cursor (cursor_withheld: true) so nothing is skipped. A delta may leave out a transaction that changed so it no longer matches the filters; re-read in full to keep a filtered list exact.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "payee_id", "type": "string", "required": true, "description": "The payee UUID to get transactions for" }, { "name": "since_date", "type": "string", "required": false, "description": "Only return transactions on or after this date. Accepts YYYY-MM-DD or natural language like \"past 30 days\". If omitted, YNAB returns only the last 12 months; pass an earlier date for older history" }, { "name": "until_date", "type": "string", "required": false, "description": "Only return transactions on or before this date (inclusive). Accepts YYYY-MM-DD or \"today\" or \"yesterday\". Prefer ISO dates for an end bound: period names such as \"last month\" or \"this year\" resolve to the START of that period, so they would exclude most of it" }, { "name": "type", "type": "\"uncategorized\" | \"unapproved\"", "required": false, "description": "Filter by transaction type: \"uncategorized\" or \"unapproved\"" }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of transactions to return (default 100, max 500)" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_import_transactions", "title": "Import Transactions (Deprecated)", "group": "transactions", "kind": "write", "deprecated": true, "summary": "DEPRECATED: This tool no longer imports anything. YNAB API 1.88 deprecated the transaction import endpoint; it does nothing and always returns an empty result. YNAB imports linked bank accounts automatically.", "asks": [], "notes": "Do NOT use this tool to sync, refresh, or pull in bank transactions. It will not fetch new transactions. To review recent transactions, use ynab_list_transactions instead.\n\nKept registered for backward compatibility only. Makes no API call and returns deprecated: true with an explanatory message and an imported_count of 0.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "include_ids", "type": "boolean", "required": false, "description": "Include imported transaction IDs in the response" } ] }, { "name": "ynab_list_scheduled_transactions", "title": "List Scheduled Transactions", "group": "scheduled-transactions", "kind": "read", "deprecated": false, "summary": "List all scheduled transactions (recurring bills, subscriptions, etc.) in a budget.", "asks": [ "Show my scheduled transactions", "What recurring bills do I have?", "List my subscriptions", "What payments are coming up?" ], "notes": "Returns scheduled transaction details including frequency, next occurrence, and amounts.\nPass since_server_knowledge (the server_knowledge of an earlier response) to get only the scheduled transactions changed since then.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "since_server_knowledge", "type": "integer", "required": false, "description": "Delta cursor: the server_knowledge from an earlier response of this tool for the same budget (and filters). When given, only entities changed since then are returned (delta: true), with deleted ones listed by id in deleted_ids; omit it for the full list" } ] }, { "name": "ynab_get_scheduled_transaction", "title": "Get Scheduled Transaction", "group": "scheduled-transactions", "kind": "read", "deprecated": false, "summary": "Get details about a specific scheduled transaction.", "asks": [ "Show me details for that scheduled transaction", "What's the info on my Netflix subscription?" ], "notes": "Requires a scheduled_transaction_id. Use ynab_list_scheduled_transactions first to find the ID.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "scheduled_transaction_id", "type": "string", "required": true, "description": "The scheduled transaction UUID to retrieve" } ] }, { "name": "ynab_create_scheduled_transaction", "title": "Create Scheduled Transaction", "group": "scheduled-transactions", "kind": "write", "deprecated": false, "summary": "Create a new scheduled transaction (recurring bill, subscription, etc.) in a budget.", "asks": [ "Schedule a recurring payment", "Add a subscription", "Set up automatic bill", "Create scheduled transaction", "Convert recurring to scheduled" ], "notes": "Requires READ_ONLY mode to be disabled (YNAB_READ_ONLY=false).\nDate must be in the future and within 5 years.\nAmount should be negative for expenses/outflows and positive for income/inflows.\nSplit limitation: YNAB cannot create scheduled transactions with splits, so a scheduled transaction has a single category. Splits are only supported when creating a regular transaction (ynab_create_transaction).", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "account_id", "type": "string", "required": true, "description": "The account UUID for this scheduled transaction" }, { "name": "date", "type": "string", "required": true, "description": "Start date in YYYY-MM-DD format (must be future, max 5 years ahead)" }, { "name": "amount", "type": "number", "required": true, "description": "Amount in dollars (negative for outflow, positive for inflow)" }, { "name": "frequency", "type": "\"never\" | \"daily\" | \"weekly\" | \"everyOtherWeek\" | \"twiceAMonth\" | \"every4Weeks\" | \"monthly\" | \"everyOtherMonth\" | \"every3Months\" | \"every4Months\" | \"twiceAYear\" | \"yearly\" | \"everyOtherYear\"", "required": true, "description": "Recurrence frequency" }, { "name": "payee_id", "type": "string", "required": false, "description": "Payee UUID" }, { "name": "payee_name", "type": "string", "required": false, "description": "Payee name (creates new payee if payee_id not provided)" }, { "name": "category_id", "type": "string", "required": false, "description": "Category UUID (Credit Card Payment categories NOT allowed)" }, { "name": "memo", "type": "string", "required": false, "description": "Transaction memo/note" }, { "name": "flag_color", "type": "\"red\" | \"orange\" | \"yellow\" | \"green\" | \"blue\" | \"purple\"", "required": false, "description": "Flag color" } ] }, { "name": "ynab_update_scheduled_transaction", "title": "Update Scheduled Transaction", "group": "scheduled-transactions", "kind": "destructive", "deprecated": false, "summary": "Update an existing scheduled transaction in a budget.", "asks": [ "Change my subscription amount", "Update recurring payment", "Modify scheduled transaction", "Change billing frequency" ], "notes": "Requires READ_ONLY mode to be disabled (YNAB_READ_ONLY=false).\nOnly provided fields will be updated.\nSplit limitation: YNAB scheduled transactions cannot have splits, and the splits of an existing split scheduled transaction cannot be edited through the API.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "scheduled_transaction_id", "type": "string", "required": true, "description": "The scheduled transaction UUID to update" }, { "name": "account_id", "type": "string", "required": false, "description": "New account UUID" }, { "name": "date", "type": "string", "required": false, "description": "New date in YYYY-MM-DD format (must be future)" }, { "name": "amount", "type": "number", "required": false, "description": "New amount in dollars (negative for outflow, positive for inflow)" }, { "name": "frequency", "type": "\"never\" | \"daily\" | \"weekly\" | \"everyOtherWeek\" | \"twiceAMonth\" | \"every4Weeks\" | \"monthly\" | \"everyOtherMonth\" | \"every3Months\" | \"every4Months\" | \"twiceAYear\" | \"yearly\" | \"everyOtherYear\"", "required": false, "description": "New recurrence frequency" }, { "name": "payee_id", "type": "string", "required": false, "description": "New payee UUID" }, { "name": "payee_name", "type": "string", "required": false, "description": "New payee name" }, { "name": "category_id", "type": "string", "required": false, "description": "New category UUID" }, { "name": "memo", "type": "string", "required": false, "description": "New memo/note" }, { "name": "flag_color", "type": "\"red\" | \"orange\" | \"yellow\" | \"green\" | \"blue\" | \"purple\" | null", "required": false, "description": "New flag color (null to remove)" } ] }, { "name": "ynab_delete_scheduled_transaction", "title": "Delete Scheduled Transaction", "group": "scheduled-transactions", "kind": "destructive", "deprecated": false, "summary": "Delete a scheduled transaction from a budget.", "asks": [ "Delete that scheduled transaction", "Remove the recurring payment", "Cancel that subscription", "Stop the scheduled bill" ], "notes": "Requires READ_ONLY mode to be disabled (YNAB_READ_ONLY=false).\nThis action cannot be undone.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "scheduled_transaction_id", "type": "string", "required": true, "description": "The scheduled transaction UUID to delete" } ] }, { "name": "ynab_detect_recurring", "title": "Detect Recurring Transactions", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Detect recurring transactions (subscriptions, bills) by analyzing transaction patterns.", "asks": [ "What subscriptions do I have?", "Find my recurring bills", "What do I pay every month?", "Detect my regular payments" ], "notes": "Analyzes transaction history to find patterns and estimates monthly costs.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "number", "required": false, "description": "Number of months to analyze (default 6)" }, { "name": "min_occurrences", "type": "number", "required": false, "description": "Minimum occurrences to consider recurring (default 3)" } ] }, { "name": "ynab_spending_analysis", "title": "Spending Analysis", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Analyze spending patterns and trends.", "asks": [ "How much am I spending?", "What are my biggest expenses?", "Show my spending trends", "Analyze my spending habits", "Where does my money go?" ], "notes": "Provides category breakdowns, trends, and insights.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "number", "required": false, "description": "Number of months to analyze (default 3)" }, { "name": "category_id", "type": "string", "required": false, "description": "Optional: Focus on a specific category" } ] }, { "name": "ynab_budget_health", "title": "Budget Health Check", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Get an overall budget health assessment.", "asks": [ "How is my budget doing?", "What's my budget status?", "Am I on track this month?", "Budget health check", "Any budget problems?" ], "notes": "Provides key metrics, alerts, and recommendations.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_savings_opportunities", "title": "Find Savings Opportunities", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Find potential savings opportunities based on spending patterns.", "asks": [ "How can I save money?", "Where can I cut back?", "What are my unnecessary expenses?", "Help me reduce spending", "Find savings opportunities" ], "notes": "Analyzes spending to identify areas where cuts might be possible.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "number", "required": false, "description": "Number of months to analyze (2-12, default 3)" } ] }, { "name": "ynab_budget_vs_actuals", "title": "Budget vs Actuals", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Compare budgeted amounts against actual spending for each category.", "asks": [ "How am I doing on my budget?", "Am I over budget anywhere?", "Compare budget vs actual", "Which categories are overspent?", "Show my budget performance" ], "notes": "Returns detailed budget vs actuals for all categories with variance analysis.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": false, "description": "Month to analyze in YYYY-MM-01 format (first of month, 01-12). Defaults to current month" }, { "name": "include_previous", "type": "boolean", "required": false, "description": "Include previous month for comparison" } ] }, { "name": "ynab_quick_summary", "title": "Quick Budget Summary", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Get a quick at-a-glance summary of the budget status.", "asks": [ "How's my budget looking?", "Give me a quick overview", "What's my financial status?", "Summary of my finances", "How much money do I have?" ], "notes": "Returns key metrics: available funds, spending this month, account balances, and alerts.\nThis is the best tool to use for general budget status questions.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_income_expense", "title": "Income vs Expenses", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Track income vs expenses with monthly breakdown.", "asks": [ "How much did I earn vs spend?", "What's my income vs expenses?", "Am I spending more than I make?", "Show my cash flow", "What's my savings rate?" ], "notes": "Returns monthly income, expenses, net savings, and savings rate.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "integer", "required": false, "description": "Number of months to analyze (default 6)" } ] }, { "name": "ynab_net_worth", "title": "Net Worth", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Calculate total net worth from all accounts.", "asks": [ "What's my net worth?", "How much do I have in total?", "Show all my account balances", "What are my assets and liabilities?" ], "notes": "Includes both budget accounts and tracking accounts (investments, property, etc.).\nReturns breakdown by account type with total assets, liabilities, and net worth.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "include_closed", "type": "boolean", "required": false, "description": "Include closed accounts in calculation (default false)" } ] }, { "name": "ynab_goal_progress", "title": "Goal Progress", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Track progress on all category goals.", "asks": [ "How are my goals doing?", "Show goal progress", "Which goals need more funding?", "Am I on track with my savings goals?", "What goals are behind?" ], "notes": "Returns goal progress, funding status, and projections for each category with a goal.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "filter", "type": "\"all\" | \"on_track\" | \"behind\" | \"underfunded\" | \"complete\" | \"snoozed\"", "required": false, "description": "Filter goals by status" } ] }, { "name": "ynab_spending_by_payee", "title": "Spending by Payee", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Analyze spending patterns by merchant/payee.", "asks": [ "Where do I spend the most?", "Top merchants by spending", "Which stores do I shop at most?", "Show spending by payee", "Who gets most of my money?" ], "notes": "Returns top payees ranked by total spending with transaction counts and averages.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "integer", "required": false, "description": "Number of months to analyze (1-12, default 3)" }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum number of payees to return (1-50, default 20)" }, { "name": "min_transactions", "type": "integer", "required": false, "description": "Minimum transactions to include payee (default 1)" } ] }, { "name": "ynab_unused_categories", "title": "Find Unused Categories", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Find categories with no recent activity.", "asks": [ "Which categories am I not using?", "Find unused categories", "Clean up my budget categories", "Categories with no activity", "What categories can I delete?" ], "notes": "Helps identify categories that could be removed or consolidated.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "number", "required": false, "description": "Number of months to check for activity (default 6)" }, { "name": "include_funded", "type": "boolean", "required": false, "description": "Include categories that have funds but no spending (default false)" } ] }, { "name": "ynab_monthly_comparison", "title": "Monthly Comparison", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Compare this month vs last month for spending and budgeting.", "asks": [ "How does this month compare to last month?", "Am I spending more or less?", "Month over month comparison", "Compare my spending", "What's changed since last month?" ], "notes": "Returns side-by-side comparison of spending, income, and category performance.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_spending_trends", "title": "Spending Trends", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Analyze spending trends over multiple months.", "asks": [ "What are my spending trends?", "How has my spending changed over time?", "Show me category trends", "Which categories are increasing?", "Am I spending more or less over time?" ], "notes": "Returns month-by-month spending data with trend analysis.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "number", "required": false, "description": "Number of months to analyze (default 6)" }, { "name": "category_id", "type": "string", "required": false, "description": "Specific category UUID to analyze (optional)" } ] }, { "name": "ynab_cash_flow_forecast", "title": "Cash Flow Forecast", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Project future cash flow based on scheduled transactions.", "asks": [ "What's my cash flow forecast?", "Will I have enough money next month?", "What bills are coming up?", "Project my account balance", "When will I run low on money?" ], "notes": "Returns projected cash flow including scheduled income and expenses.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "days", "type": "number", "required": false, "description": "Number of days to forecast (default 30)" } ] }, { "name": "ynab_reconciliation_helper", "title": "Reconciliation Helper", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Help with account reconciliation by showing uncleared transactions.", "asks": [ "Help me reconcile my accounts", "What transactions haven't cleared?", "Show uncleared transactions", "Pending transactions", "Reconciliation status" ], "notes": "Returns uncleared transactions organized by account with totals.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "account_id", "type": "string", "required": false, "description": "Specific account ID to check (optional)" } ] }, { "name": "ynab_budget_suggestions", "title": "Budget Suggestions", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Suggest budget amounts based on historical spending.", "asks": [ "How much should I budget for [category]?", "Suggest budget amounts", "What's a realistic budget?", "Help me set my budget", "Based on my spending, what should I budget?" ], "notes": "Returns suggested monthly budget amounts for each category based on actual spending patterns.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "months", "type": "integer", "required": false, "description": "Number of months of history to analyze (1-12, default 3)" } ] }, { "name": "ynab_overspending_alerts", "title": "Overspending Alerts", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Check for categories that are currently overspent.", "asks": [ "Am I overspending?", "What categories are over budget?", "Any overspending alerts?", "Where am I in the red?", "Check my budget status" ], "notes": "Returns a quick list of all overspent categories with amounts.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "threshold", "type": "number", "required": false, "description": "Minimum overspend amount to report in dollars (default 0)" } ] }, { "name": "ynab_transaction_search", "title": "Search Transactions", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Search transactions with powerful filtering options.", "asks": [ "Find transactions at [store]", "Search for [keyword] in my transactions", "Transactions over $100", "What did I spend on [category]?", "Find large purchases", "Search my expenses" ], "notes": "Supports filtering by payee, category, amount range, date range, and text search.\n\nNOTE: If since_date is omitted, YNAB returns only the last 12 months of transactions (API 1.85 default). If only until_date is given, the search starts at the budget's first month so older ranges work (may fetch many transactions; still one request).", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "query", "type": "string", "required": false, "description": "Search text to match in payee name, memo, or category" }, { "name": "payee", "type": "string", "required": false, "description": "Filter by payee name (partial match)" }, { "name": "category", "type": "string", "required": false, "description": "Filter by category name (partial match)" }, { "name": "min_amount", "type": "number", "required": false, "description": "Minimum transaction amount in dollars (absolute value)" }, { "name": "max_amount", "type": "number", "required": false, "description": "Maximum transaction amount in dollars (absolute value)" }, { "name": "since_date", "type": "string", "required": false, "description": "Start date (YYYY-MM-DD or natural language). If omitted, YNAB returns only the last 12 months, unless until_date is given (then the search starts at the budget's first month)." }, { "name": "until_date", "type": "string", "required": false, "description": "End date, inclusive (YYYY-MM-DD or natural language). Prefer ISO dates: period names such as \"last month\" resolve to the START of that period, so they would exclude most of it. Applied server-side. Without since_date this searches from the budget's first month, which can fetch a lot of data." }, { "name": "type", "type": "\"all\" | \"inflow\" | \"outflow\"", "required": false, "description": "Filter by transaction type" }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum results to return (default 25)" } ] }, { "name": "ynab_spending_pace", "title": "Spending Pace", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Track daily spending rate and project end-of-month status.", "asks": [ "Am I on track this month?", "What's my spending pace?", "Will I stay within budget?", "How much can I spend per day?", "Daily spending rate" ], "notes": "Returns current spending rate vs target rate with projections.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_category_balances", "title": "Category Balances", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Check category balances with optional filtering.", "asks": [ "What's my balance in [category]?", "How much do I have for groceries?", "Show category balances", "Which categories have money?", "What categories are negative?" ], "notes": "Returns current category balances with filtering options.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "filter", "type": "\"all\" | \"funded\" | \"unfunded\" | \"negative\" | \"positive\"", "required": false, "description": "Filter categories by balance status" }, { "name": "group", "type": "string", "required": false, "description": "Filter by category group name (partial match)" }, { "name": "search", "type": "string", "required": false, "description": "Search category names (partial match)" } ] }, { "name": "ynab_credit_card_status", "title": "Credit Card Status", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Check credit card balances and payment category status.", "asks": [ "What's my credit card balance?", "How much do I owe on credit cards?", "Credit card payment status", "Do I have enough to pay my credit cards?", "Show credit card accounts" ], "notes": "Returns credit card balances with corresponding payment category balances.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_age_of_money", "title": "Age of Money", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Get the Age of Money metric with explanation and tips.", "asks": [ "What's my age of money?", "How old is my money?", "Explain age of money", "Am I living on last month's income?", "How long does my money last?" ], "notes": "Returns the current age of money with context and improvement tips.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" } ] }, { "name": "ynab_preview_scheduled_transaction", "title": "Preview Scheduled Transactions", "group": "analytics", "kind": "read", "deprecated": false, "summary": "Preview a scheduled transaction before creating it.", "asks": [ "Show me what this scheduled transaction would look like", "Preview recurring payment", "What would this subscription cost annually?", "Validate scheduled transaction" ], "notes": "Validates all inputs and returns a preview with estimated costs.\nDoes NOT create anything - use ynab_create_scheduled_transaction to actually create.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "account_id", "type": "string", "required": true, "description": "The account UUID for this scheduled transaction" }, { "name": "amount", "type": "number", "required": true, "description": "Amount in dollars (negative for outflow, positive for inflow)" }, { "name": "frequency", "type": "\"never\" | \"daily\" | \"weekly\" | \"everyOtherWeek\" | \"twiceAMonth\" | \"every4Weeks\" | \"monthly\" | \"everyOtherMonth\" | \"every3Months\" | \"every4Months\" | \"twiceAYear\" | \"yearly\" | \"everyOtherYear\"", "required": true, "description": "Recurrence frequency" }, { "name": "payee_id", "type": "string", "required": false, "description": "Payee UUID" }, { "name": "payee_name", "type": "string", "required": false, "description": "Payee name" }, { "name": "category_id", "type": "string", "required": false, "description": "Category UUID" }, { "name": "start_date", "type": "string", "required": false, "description": "Start date in YYYY-MM-DD format" }, { "name": "memo", "type": "string", "required": false, "description": "Transaction memo/note" }, { "name": "flag_color", "type": "\"red\" | \"orange\" | \"yellow\" | \"green\" | \"blue\" | \"purple\"", "required": false, "description": "Flag color" } ] }, { "name": "ynab_list_money_movements", "title": "List Money Movements", "group": "money-movements", "kind": "read", "deprecated": false, "summary": "List money movements (moves of funds between categories) for a budget.", "asks": [ "Show me my money moves between categories", "When did I move money out of [category]?", "List my category fund transfers", "What money did I move in [month]?" ], "notes": "Returns each movement's amount (formatted, plus amount_milliunits), the categories it moved between, when it happened and who performed it (performed_by_user_id, masked). Pass month (YYYY-MM-01 or \"current\") to limit to a single budget month. Pass group_by_group=true to get movements nested under their money movement group (money_movement_groups[].movements, plus ungrouped_movements) instead of a flat list; it costs one extra request.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": false, "description": "Only return movements for this budget month: YYYY-MM-01 (first of month) or \"current\"" }, { "name": "group_by_group", "type": "boolean", "required": false, "description": "Nest movements under their money movement group (one extra request for the groups). Default false" } ] }, { "name": "ynab_list_money_movement_groups", "title": "List Money Movement Groups", "group": "money-movements", "kind": "read", "deprecated": false, "summary": "List money movement groups: batches of category-to-category fund moves that were made together.", "asks": [ "Which budget rebalancing batches did I do?", "Show my money move groups for [month]", "What were the notes on my category fund moves?" ], "notes": "Each group has an id, creation time, month, note and who performed it (performed_by_user_id, masked). Use the group id to match entries from ynab_list_money_movements (money_movement_group_id). Pass month (YYYY-MM-01 or \"current\") to limit to one budget month.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "budget_id", "type": "string", "required": false, "description": "Budget UUID, \"last-used\", or \"default\". Defaults to YNAB_BUDGET_ID env var or \"last-used\"" }, { "name": "month", "type": "string", "required": false, "description": "Only return groups for this budget month: YYYY-MM-01 (first of month) or \"current\"" } ] }, { "name": "ynab_rate_limit_status", "title": "Rate Limit Status", "group": "system", "kind": "read", "deprecated": false, "summary": "Check the current YNAB API rate limit status.", "asks": [], "notes": "Use when you need to:\n- Check how many API requests are available\n- See if rate limiting might affect operations\n- Plan large operations that require many API calls\n\nYNAB allows 200 requests per hour. This server uses 180 as a safety margin. If YNAB itself has answered 429 (too many requests), ynab_exhausted shows when that happened and when requests are allowed again; until then requests fail fast.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [] }, { "name": "ynab_audit_log", "title": "View Audit Log", "group": "system", "kind": "read", "deprecated": false, "summary": "View the audit log of write operations.", "asks": [ "What changes have been made?", "Show me the audit log", "What transactions were created?", "Were there any failed operations?" ], "notes": "Shows all create, update, and delete operations with timestamps.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "operation", "type": "\"create\" | \"update\" | \"delete\"", "required": false, "description": "Filter by operation type" }, { "name": "resource_type", "type": "\"transaction\" | \"account\" | \"category\"", "required": false, "description": "Filter by resource type" }, { "name": "success", "type": "boolean", "required": false, "description": "Filter by success/failure" }, { "name": "limit", "type": "integer", "required": false, "description": "Maximum entries to return (default 20)" }, { "name": "summary_only", "type": "boolean", "required": false, "description": "Return only summary statistics" } ] }, { "name": "ynab_health_check", "title": "Health Check", "group": "system", "kind": "read", "deprecated": false, "summary": "Check the health of the YNAB MCP server and API connection.", "asks": [], "notes": "Use when:\n- Troubleshooting connection issues\n- Verifying the server is configured correctly\n- Checking if the YNAB API is accessible\n\nReturns server status, API connectivity, and configuration details.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [] } ], "prompts": [ { "name": "ynab-pulse-check", "title": "Pulse Check", "description": "Fast daily-style status check: Ready to Assign, overspending flags, spending pace, and an overall health score. Use for \"how am I doing this month\", \"how's my budget looking\", \"quick check on my finances\", or \"am I on track\". Not for a full monthly review (use ynab-monthly-review) or fixing overspending (use ynab-overspending-triage).", "arguments": [] }, { "name": "ynab-monthly-review", "title": "Monthly Review", "description": "Runs a complete end-of-month budget review: this month's performance vs. plan, goal progress, income/savings trend, net worth change, and suggested targets for next month. Use for \"let's do my monthly budget review\", \"end of month check-in\", \"how did this month go\", \"review my budget\", \"close out this month\", or \"help me plan next month's budget\". Not for a quick daily-style check (use ynab-pulse-check), or deep reconciliation/cash-flow work (use ynab-reconcile-cleanup / ynab-age-of-money) — this flags those but doesn't deep-dive them.", "arguments": [ { "name": "month", "required": false, "description": "Month to review in YYYY-MM-01 format (first of month). Defaults to the current month." } ] }, { "name": "ynab-assign-money", "title": "Assign Money", "description": "Helps give every dollar a job: assigns unallocated Ready to Assign money to categories, funds underfunded goals, and sets up new categories. Use for \"I have money to assign\", \"help me budget this month\", \"what should I fund\", \"help me set up a new category\", \"organize my budget categories\", or \"assign my leftover funds\". Not for fixing already-overspent categories (use ynab-overspending-triage) or the initial category structure of a brand-new budget (that's a bigger first-time-setup conversation).", "arguments": [] }, { "name": "ynab-true-expenses", "title": "True Expenses", "description": "Finds and plans for irregular or infrequent costs — annual subscriptions, car repairs, holiday spending, insurance premiums — and detects recurring bills that may be missing from the budget or scheduled transactions. Use for \"help me plan for an annual expense\", \"I have a big bill coming up\", \"make sure my recurring bills are captured\", \"set up a sinking fund\", \"did I forget any subscriptions\", or \"embrace my true expenses\". Not for general new-category creation unrelated to irregular costs (use ynab-assign-money) or fixing an already-overspent category (use ynab-overspending-triage).", "arguments": [] }, { "name": "ynab-overspending-triage", "title": "Overspending Triage", "description": "Finds where money is being overspent and helps roll with the punches: move funds from categories with slack, and surface discretionary cuts. Use for \"find places I'm overspending\", \"where did I overspend\", \"help me fix overspending\", \"roll with the punches\", \"where can I find extra money\", or \"help me cut back this month\". Not for computing true-expense monthly contributions (use ynab-true-expenses) or the initial \"assign new money\" pass (use ynab-assign-money) — this is remediation of overspending, not allocation of unassigned money.", "arguments": [] }, { "name": "ynab-age-of-money", "title": "Age of Money Check", "description": "Checks how healthy the cash cushion is: Age of Money, near-term cash flow forecast, and whether the credit card float is quietly draining the buffer. Use for \"check my age of money\", \"am I living paycheck to paycheck\", \"how's my cash flow\", \"will I have enough before payday\", or \"is my credit card float catching up to me\". Not for the overall month scorecard (use ynab-monthly-review, which references this in one line but doesn't forecast) or fixing overspending that's causing a low Age of Money (use ynab-overspending-triage).", "arguments": [] }, { "name": "ynab-reconcile-cleanup", "title": "Reconcile Cleanup", "description": "Runs the weekly housekeeping pass: flags uncleared transactions per account for reconciliation, and audits the budget for unused or overly-granular (\"sprawl\") categories worth merging or archiving. Use for \"let's reconcile my accounts\", \"clean up my budget\", \"find categories I don't use\", \"check for uncleared transactions\", or \"audit my budget for clutter\". Not for spending analysis or overspending remediation — purely data-integrity and structure hygiene.", "arguments": [] } ] }