ynab-mcp

Instructions

Implementation Reference

• src/tools/months.ts:30-61 (handler)

  The "get_month" tool handler, which retrieves detailed budget month information including category balances from the YNAB API.

  server.registerTool("get_month", {
    title: "Get Budget Month",
    description: "[1 API call] Get detailed info for a single budget month including all category balances. Use 'current' for the current month.",
    inputSchema: {
      budget_id: z.string().default("last-used").describe("Budget ID or 'last-used'"),
      month: z.string().describe("Month in YYYY-MM-DD format (first of month) or 'current'"),
    },
    annotations: { readOnlyHint: true },
  }, async ({ budget_id, month }) => {
    try {
      const response = await getClient().months.getPlanMonth(budget_id, month);
      const m = response.data.month;
      const lines = [
        `Month: ${m.month}`,
        `Income: ${formatCurrency(m.income)}`,
        `Budgeted: ${formatCurrency(m.budgeted)}`,
        `Activity: ${formatCurrency(m.activity)}`,
        `To Be Budgeted: ${formatCurrency(m.to_be_budgeted)}`,
        `Age of Money: ${m.age_of_money ?? "N/A"} days`,
      ];
      if (m.categories) {
        lines.push(`\nCategories:`);
        for (const c of m.categories) {
          if (c.hidden) continue;
          lines.push(`  - ${c.name}: Budgeted ${formatCurrency(c.budgeted)} | Activity ${formatCurrency(c.activity)} | Balance ${formatCurrency(c.balance)}`);
        }
      }
      return textResult(lines.join("\n"));
    } catch (e: any) {
      return errorResult(e.message);
    }
  });