create_scheduled_transaction

Instructions

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    account_id: The account ID for this scheduled transaction
    date_first: The first date the transaction should occur (YYYY-MM-DD format)
    frequency: Frequency (never, daily, weekly, everyOtherWeek, twiceAMonth, every4Weeks, monthly, everyOtherMonth, every3Months, every4Months, twiceAYear, yearly, everyOtherYear)
    amount: Transaction amount (positive for inflow, negative for outflow)
    payee_name: Name of the payee (optional)
    category_id: Category ID (optional)
    memo: Transaction memo (optional)
    flag_color: Flag color - red, orange, yellow, green, blue, purple (optional)

Returns:
    JSON string with the created scheduled transaction

Implementation Reference

• src/ynab_mcp/server.py:358-398 (handler)

  MCP tool handler and registration for 'create_scheduled_transaction'. Decorated with @mcp.tool(), defines input schema via type hints and docstring, delegates to YNABClient.

  @mcp.tool()
  async def create_scheduled_transaction(
      budget_id: str,
      account_id: str,
      date_first: str,
      frequency: str,
      amount: float,
      payee_name: str = None,
      category_id: str = None,
      memo: str = None,
      flag_color: str = None,
  ) -> str:
      """Create a scheduled transaction (for future/recurring transactions).
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          account_id: The account ID for this scheduled transaction
          date_first: The first date the transaction should occur (YYYY-MM-DD format)
          frequency: Frequency (never, daily, weekly, everyOtherWeek, twiceAMonth, every4Weeks, monthly, everyOtherMonth, every3Months, every4Months, twiceAYear, yearly, everyOtherYear)
          amount: Transaction amount (positive for inflow, negative for outflow)
          payee_name: Name of the payee (optional)
          category_id: Category ID (optional)
          memo: Transaction memo (optional)
          flag_color: Flag color - red, orange, yellow, green, blue, purple (optional)
  
      Returns:
          JSON string with the created scheduled transaction
      """
      client = get_ynab_client()
      result = await client.create_scheduled_transaction(
          budget_id,
          account_id,
          date_first,
          frequency,
          amount,
          payee_name,
          category_id,
          memo,
          flag_color,
      )
      return json.dumps(result, indent=2)

• src/ynab_mcp/ynab_client.py:1123-1189 (helper)

  Core implementation of scheduled transaction creation in YNABClient class. Constructs API payload and performs POST request to YNAB /scheduled_transactions endpoint.

  async def create_scheduled_transaction(
      self,
      budget_id: str,
      account_id: str,
      date_first: str,
      frequency: str,
      amount: float,
      payee_name: str | None = None,
      category_id: str | None = None,
      memo: str | None = None,
      flag_color: str | None = None,
  ) -> dict[str, Any]:
      """Create a scheduled transaction.
  
      Args:
          budget_id: The budget ID or 'last-used'
          account_id: The account ID
          date_first: The first date the transaction should occur (YYYY-MM-DD)
          frequency: Frequency (never, daily, weekly, everyOtherWeek, twiceAMonth, every4Weeks, monthly, everyOtherMonth, every3Months, every4Months, twiceAYear, yearly, everyOtherYear)
          amount: Transaction amount (positive for inflow, negative for outflow)
          payee_name: Payee name (optional)
          category_id: Category ID (optional)
          memo: Transaction memo (optional)
          flag_color: Flag color (red, orange, yellow, green, blue, purple, optional)
  
      Returns:
          Created scheduled transaction dictionary
      """
      try:
          url = f"{self.api_base_url}/budgets/{budget_id}/scheduled_transactions"
  
          scheduled_transaction_data = {
              "account_id": account_id,
              "date": date_first,
              "frequency": frequency,
              "amount": int(amount * 1000),  # Convert to milliunits
          }
  
          if payee_name is not None:
              scheduled_transaction_data["payee_name"] = payee_name
          if category_id is not None:
              scheduled_transaction_data["category_id"] = category_id
          if memo is not None:
              scheduled_transaction_data["memo"] = memo
          if flag_color is not None:
              scheduled_transaction_data["flag_color"] = flag_color
  
          data = {"scheduled_transaction": scheduled_transaction_data}
  
          result = await self._make_request_with_retry("post", url, json=data)
  
          txn = result["data"]["scheduled_transaction"]
  
          return {
              "id": txn["id"],
              "date_first": txn.get("date_first"),
              "date_next": txn.get("date_next"),
              "frequency": txn.get("frequency"),
              "amount": txn["amount"] / 1000 if txn.get("amount") else 0,
              "memo": txn.get("memo"),
              "flag_color": txn.get("flag_color"),
              "account_id": txn.get("account_id"),
              "payee_name": txn.get("payee_name"),
              "category_id": txn.get("category_id"),
          }
      except Exception as e:
          raise Exception(f"Failed to create scheduled transaction: {e}") from e