ynab-mcp

Instructions

Implementation Reference

• src/tools/scheduled-transactions.ts:79-94 (registration)

  Registration of the "create_scheduled_transaction" tool, defining its metadata and input schema.

  server.registerTool("create_scheduled_transaction", {
    title: "Create Scheduled Transaction",
    description: "[1 API call] Create a new scheduled (recurring) transaction. Date must be in the future (up to 5 years).",
    inputSchema: {
      budget_id: z.string().default("last-used").describe("Budget ID or 'last-used'"),
      account_id: z.string().describe("Account ID"),
      date: z.string().describe("First occurrence date (YYYY-MM-DD), must be future"),
      amount: z.number().describe("Amount in dollars (negative for outflows)"),
      frequency: z.enum(FREQUENCIES).describe("How often the transaction repeats"),
      payee_id: z.string().optional().describe("Payee ID"),
      payee_name: z.string().optional().describe("Payee name"),
      category_id: z.string().optional().describe("Category ID (cannot be credit card payment)"),
      memo: z.string().optional().describe("Memo"),
      flag_color: z.enum(FLAG_COLORS).optional().describe("Flag color"),
    },
    annotations: { readOnlyHint: false },

• src/tools/scheduled-transactions.ts:95-117 (handler)

  Handler implementation for "create_scheduled_transaction", which communicates with the YNAB client API to create the transaction.

  }, async ({ budget_id, account_id, date, amount, frequency, payee_id, payee_name, category_id, memo, flag_color }) => {
    try {
      const response = await getClient().scheduledTransactions.createScheduledTransaction(budget_id, {
        scheduled_transaction: {
          account_id,
          date,
          amount: dollarsToMilliunits(amount),
          frequency,
          payee_id,
          payee_name,
          category_id,
          memo,
          flag_color: flag_color ?? null,
        },
      });
      const t = response.data.scheduled_transaction;
      return textResult(
        `Created scheduled transaction: ${t.date_first} | ${formatCurrency(t.amount)} | ${t.payee_name ?? "No payee"} | ${t.frequency}\nID: ${t.id}`
      );
    } catch (e: any) {
      return errorResult(e.message);
    }
  });