YNAB MCP Server

Instructions

Implementation Reference

• src/tools/ListScheduledTransactionsTool.ts:23-71 (handler)

  The execute function implementing the core logic: retrieves scheduled transactions from YNAB API, filters out deleted ones, formats the data, and returns it as JSON-formatted text content or error.

  export async function execute(input: ListScheduledTransactionsInput, api: ynab.API) {
    try {
      const budgetId = getBudgetId(input.budgetId);
  
      console.error(`Listing scheduled transactions for budget ${budgetId}`);
      const response = await api.scheduledTransactions.getScheduledTransactions(budgetId);
  
      // Filter and format scheduled transactions
      const scheduledTransactions = response.data.scheduled_transactions
        .filter((txn) => !txn.deleted)
        .map((txn) => ({
          id: txn.id,
          date_first: txn.date_first,
          date_next: txn.date_next,
          frequency: txn.frequency,
          amount: (txn.amount / 1000).toFixed(2),
          memo: txn.memo,
          flag_color: txn.flag_color,
          account_id: txn.account_id,
          account_name: txn.account_name,
          payee_id: txn.payee_id,
          payee_name: txn.payee_name,
          category_id: txn.category_id,
          category_name: txn.category_name,
          transfer_account_id: txn.transfer_account_id,
        }));
  
      return {
        content: [{
          type: "text" as const,
          text: JSON.stringify({
            scheduled_transactions: scheduledTransactions,
            count: scheduledTransactions.length,
          }, null, 2),
        }],
      };
    } catch (error) {
      console.error("Error listing scheduled transactions:", error);
      return {
        content: [{
          type: "text" as const,
          text: JSON.stringify({
            success: false,
            error: getErrorMessage(error),
          }, null, 2),
        }],
      };
    }
  }

• src/tools/ListScheduledTransactionsTool.ts:7-9 (schema)

  Input schema definition using Zod for optional budgetId parameter.

  export const inputSchema = {
    budgetId: z.string().optional().describe("The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable)"),
  };

• src/index.ts:111-115 (registration)

  Registers the tool with the MCP server, providing name, title, description, inputSchema, and the async handler wrapping the execute function with the YNAB API instance.

  server.registerTool(ListScheduledTransactionsTool.name, {
    title: "List Scheduled Transactions",
    description: ListScheduledTransactionsTool.description,
    inputSchema: ListScheduledTransactionsTool.inputSchema,
  }, async (input) => ListScheduledTransactionsTool.execute(input, api));