List Months
ynab_list_monthsRetrieve a list of all budget months with summary information about budgeting status for financial tracking and planning.
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 main handler function that executes the tool logic: fetches budget months from YNAB API, formats them, and returns as JSON text response. Handles errors gracefully.
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/index.ts:123-127 (registration)Registers the 'ynab_list_months' tool with the MCP server, providing title, description, input schema, and delegating execution to the tool's execute function.
server.registerTool(ListMonthsTool.name, { title: "List Months", description: ListMonthsTool.description, inputSchema: ListMonthsTool.inputSchema, }, async (input) => ListMonthsTool.execute(input, api)); - src/tools/ListMonthsTool.ts:7-9 (schema)Zod-based input schema defining the optional budgetId parameter for the tool.
export const inputSchema = { budgetId: z.string().optional().describe("The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable)"), }; - src/tools/ListMonthsTool.ts:15-21 (helper)Helper function to resolve the budget ID from input parameter or YNAB_BUDGET_ID environment variable, throwing error if missing.
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/index.ts:22-22 (registration)Import of the ListMonthsTool module in the main index file for registration.
import * as ListMonthsTool from "./tools/ListMonthsTool.js";