ynab_update_category_budget
Adjust budgeted amounts for specific categories in YNAB to allocate funds or reallocate money between spending areas for precise financial planning.
Instructions
Updates the budgeted amount for a category in a specific month. Use this to allocate funds to categories or move money between categories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budgetId | No | The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable) | |
| month | Yes | The budget month in ISO format (e.g. 2024-01-01). Must be the first day of the month. | |
| categoryId | Yes | The ID of the category to update | |
| budgeted | Yes | The amount to budget in dollars (e.g. 500.00). This sets the total budgeted amount, not an increment. |
Implementation Reference
- The execute function that handles the tool logic: resolves budget ID, converts amount to milliunits, calls YNAB API to update category budget, and returns success/error response.export async function execute(input: UpdateCategoryBudgetInput, api: ynab.API) { try { const budgetId = getBudgetId(input.budgetId); const budgetedMilliunits = Math.round(input.budgeted * 1000); const response = await api.categories.updateMonthCategory( budgetId, input.month, input.categoryId, { category: { budgeted: budgetedMilliunits, }, } ); if (!response.data.category) { throw new Error("Failed to update category - no category data returned"); } const category = response.data.category; return { content: [{ type: "text" as const, text: JSON.stringify({ success: true, category: { id: category.id, name: category.name, budgeted: (category.budgeted / 1000).toFixed(2), activity: (category.activity / 1000).toFixed(2), balance: (category.balance / 1000).toFixed(2), }, message: `Successfully updated ${category.name} budget to $${(category.budgeted / 1000).toFixed(2)}`, }, null, 2), }], }; } catch (error) { console.error("Error updating category budget:", error); return { content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: getErrorMessage(error), }, null, 2), }], }; } }
- Zod-based input schema defining parameters for the tool: budgetId (optional), month (ISO date), categoryId, budgeted amount.export const inputSchema = { budgetId: z.string().optional().describe("The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable)"), month: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("The budget month in ISO format (e.g. 2024-01-01). Must be the first day of the month."), categoryId: z.string().describe("The ID of the category to update"), budgeted: z.number().describe("The amount to budget in dollars (e.g. 500.00). This sets the total budgeted amount, not an increment."), };
- src/index.ts:63-67 (registration)Registers the tool with the MCP server using the name, title, description, inputSchema from the tool module, and a wrapper async handler that invokes the tool's execute function with the YNAB API instance.server.registerTool(UpdateCategoryBudgetTool.name, { title: "Update Category Budget", description: UpdateCategoryBudgetTool.description, inputSchema: UpdateCategoryBudgetTool.inputSchema, }, async (input) => UpdateCategoryBudgetTool.execute(input, api));
- Helper function to retrieve the budget ID from input parameter or 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; }