Budget Summary
ynab_budget_summaryAnalyze monthly budget performance by identifying overspent categories requiring attention and categories with positive balances performing well.
Instructions
Get a summary of the budget for a specific month highlighting overspent categories that need attention and categories with a positive balance that are doing well.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budgetId | No | The ID of the budget to get a summary for (optional, defaults to the budget set in the YNAB_BUDGET_ID environment variable) | |
| month | No | The budget month in ISO format (e.g. 2016-12-01). The string 'current' can also be used to specify the current calendar month (UTC) | current |
Implementation Reference
- src/tools/BudgetSummaryTool.ts:25-59 (handler)The main handler function that fetches active accounts and categories for the specified budget month and returns a JSON summary, handling errors gracefully.
export async function execute(input: BudgetSummaryInput, api: ynab.API) { try { const budgetId = getBudgetId(input.budgetId); const month = input.month || "current"; console.error(`Getting accounts and categories for budget ${budgetId} and month ${month}`); const accountsResponse = await api.accounts.getAccounts(budgetId); const accounts = accountsResponse.data.accounts.filter( (account) => account.deleted === false && account.closed === false ); const monthBudget = await api.months.getBudgetMonth(budgetId, month); const categories = monthBudget.data.month.categories .filter( (category) => category.deleted === false && category.hidden === false ); return { content: [{ type: "text" as const, text: JSON.stringify({ monthBudget: monthBudget.data.month, accounts: accounts, note: "Divide all numbers by 1000 to get the balance in dollars.", }, null, 2) }] }; } catch (error: unknown) { console.error("Error getting budget summary:", error); return { content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: getErrorMessage(error), }, null, 2) }] }; } } - src/tools/BudgetSummaryTool.ts:5-10 (schema)Exports the tool name, description, and Zod input schema defining optional budgetId and month parameters.
export const name = "ynab_budget_summary"; export const description = "Get a summary of the budget for a specific month highlighting overspent categories that need attention and categories with a positive balance that are doing well."; export const inputSchema = { budgetId: z.string().optional().describe("The ID of the budget to get a summary for (optional, defaults to the budget set in the YNAB_BUDGET_ID environment variable)"), month: z.string().regex(/^(current|\d{4}-\d{2}-\d{2})$/).default("current").describe("The budget month in ISO format (e.g. 2016-12-01). The string 'current' can also be used to specify the current calendar month (UTC)"), }; - src/index.ts:45-49 (registration)Registers the ynab_budget_summary tool with the MCP server using the imported name, description, inputSchema, and a wrapper around the execute handler.
server.registerTool(BudgetSummaryTool.name, { title: "Budget Summary", description: BudgetSummaryTool.description, inputSchema: BudgetSummaryTool.inputSchema, }, async (input) => BudgetSummaryTool.execute(input, api)); - src/tools/BudgetSummaryTool.ts:17-23 (helper)Helper function to retrieve the budget ID from input or environment variable, throwing an error if not available.
function getBudgetId(inputBudgetId?: string): string { const budgetId = inputBudgetId || process.env.YNAB_BUDGET_ID || ""; if (!budgetId) { throw new Error("No budget ID provided. Please provide a budget ID or set the YNAB_BUDGET_ID environment variable."); } return budgetId; }