List Months
ynab_list_monthsRetrieve all budget months with summary information on income, activity, and budgeted amounts to quickly review budgeting status for any specified budget.
Instructions
Lists all budget months. Each month contains summary information about budgeting status.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budgetId | No | The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable) |
Implementation Reference
- src/tools/ListMonthsTool.ts:23-62 (handler)The execute function that calls the YNAB API to list budget months, formats the response with income/budgeted/activity/to_be_budgeted values, and returns the result.
export async function execute(input: ListMonthsInput, api: ynab.API) { try { const budgetId = getBudgetId(input.budgetId); console.error(`Listing months for budget ${budgetId}`); const response = await api.months.getBudgetMonths(budgetId); // Format the months const months = response.data.months.map((month) => ({ month: month.month, note: month.note, income: (month.income / 1000).toFixed(2), budgeted: (month.budgeted / 1000).toFixed(2), activity: (month.activity / 1000).toFixed(2), to_be_budgeted: (month.to_be_budgeted / 1000).toFixed(2), age_of_money: month.age_of_money, })); return { content: [{ type: "text" as const, text: JSON.stringify({ months, month_count: months.length, }, null, 2), }], }; } catch (error) { console.error("Error listing months:", error); return { content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: getErrorMessage(error), }, null, 2), }], }; } } - src/tools/ListMonthsTool.ts:7-9 (schema)Input schema definition using zod - accepts an optional budgetId string parameter.
export const inputSchema = { budgetId: z.string().optional().describe("The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable)"), }; - src/index.ts:123-127 (registration)Registration of the tool with the MCP server using server.registerTool(), binding the name, description, inputSchema, and execute handler.
server.registerTool(ListMonthsTool.name, { title: "List Months", description: ListMonthsTool.description, inputSchema: ListMonthsTool.inputSchema, }, async (input) => ListMonthsTool.execute(input, api)); - src/tools/ListMonthsTool.ts:15-21 (helper)Helper function getBudgetId() that resolves the budget ID from input or falls back to the YNAB_BUDGET_ID environment variable.
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; } - src/tools/ListMonthsTool.ts:5-5 (registration)Tool name constant 'ynab_list_months' and description exported from the tool module.
export const name = "ynab_list_months";