YNAB MCP Server

Instructions

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