YNAB MCP Server

Instructions

Implementation Reference

• src/tools/CreateTransactionTool.ts:43-93 (handler)

  Main handler function that executes the YNAB transaction creation logic using the YNAB API.

  export async function execute(input: CreateTransactionInput, api: ynab.API) {
    try {
      const budgetId = getBudgetId(input.budgetId);
  
      if(!input.payeeId && !input.payeeName) {
        throw new Error("Either payeeId or payeeName must be provided");
      }
  
      const milliunitAmount = Math.round(input.amount * 1000);
  
      const transaction: ynab.PostTransactionsWrapper = {
        transaction: {
          account_id: input.accountId,
          date: input.date,
          amount: milliunitAmount,
          payee_id: input.payeeId,
          payee_name: input.payeeName,
          category_id: input.categoryId,
          memo: input.memo,
          cleared: input.cleared ? ynab.TransactionClearedStatus.Cleared : ynab.TransactionClearedStatus.Uncleared,
          approved: input.approved ?? false,
          flag_color: input.flagColor as ynab.TransactionFlagColor,
        }
      };
  
      const response = await api.transactions.createTransaction(
        budgetId,
        transaction
      );
  
      if (!response.data.transaction) {
        throw new Error("Failed to create transaction - no transaction data returned");
      }
  
      return {
        content: [{ type: "text" as const, text: JSON.stringify({
          success: true,
          transactionId: response.data.transaction.id,
          message: "Transaction created successfully",
        }, null, 2) }]
      };
    } catch (error) {
      console.error("Error creating transaction:", error);
      return {
        content: [{ type: "text" as const, text: JSON.stringify({
          success: false,
          error: getErrorMessage(error),
        }, null, 2) }]
      };
    }
  }

• src/tools/CreateTransactionTool.ts:5-19 (schema)

  Tool name, description, and input schema definition using Zod.

  export const name = "ynab_create_transaction";
  export const description = "Creates a new transaction in your YNAB budget. Either payeeId or payeeName must be provided in addition to the other required fields.";
  export const inputSchema = {
    budgetId: z.string().optional().describe("The id of the budget to create the transaction in (optional, defaults to the budget set in the YNAB_BUDGET_ID environment variable)"),
    accountId: z.string().describe("The id of the account to create the transaction in"),
    date: z.string().describe("The date of the transaction in ISO format (e.g. 2024-03-24)"),
    amount: z.number().describe("The amount in dollars (e.g. 10.99)"),
    payeeId: z.string().optional().describe("The id of the payee (optional if payeeName is provided)"),
    payeeName: z.string().optional().describe("The name of the payee (optional if payeeId is provided)"),
    categoryId: z.string().optional().describe("The category id for the transaction (optional)"),
    memo: z.string().optional().describe("A memo/note for the transaction (optional)"),
    cleared: z.boolean().optional().describe("Whether the transaction is cleared (optional, defaults to false)"),
    approved: z.boolean().optional().describe("Whether the transaction is approved (optional, defaults to false)"),
    flagColor: z.string().optional().describe("The transaction flag color (red, orange, yellow, green, blue, purple) (optional)"),
  };

• src/index.ts:51-55 (registration)

  Registers the ynab_create_transaction tool with the MCP server, providing the handler wrapper.

  server.registerTool(CreateTransactionTool.name, {
    title: "Create Transaction",
    description: CreateTransactionTool.description,
    inputSchema: CreateTransactionTool.inputSchema,
  }, async (input) => CreateTransactionTool.execute(input, api));

• src/tools/CreateTransactionTool.ts:35-41 (helper)

  Helper function to retrieve or default the budget ID from input or 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;
  }