YNAB MCP Server

Instructions

Implementation Reference

• src/ynab_mcp/server.py:527-589 (handler)

  MCP tool handler: parses subtransactions JSON, calls YNABClient.create_split_transaction, serializes response to JSON. Registered via @mcp.tool() decorator which also defines input schema via type hints and docstring.
  @mcp.tool() async def create_split_transaction( budget_id: str, account_id: str, date: str, amount: float, subtransactions: str, payee_name: str = None, memo: str = None, cleared: str = "uncleared", approved: bool = False, ) -> str: """Create a NEW split transaction with multiple category allocations. This tool creates a brand new transaction that is split across multiple categories. It CANNOT be used to add splits to an existing transaction - the YNAB API does not support that. Args: budget_id: The ID of the budget (use 'last-used' for default budget) account_id: The account ID for this transaction date: Transaction date in YYYY-MM-DD format amount: Total transaction amount (positive for inflow, negative for outflow) subtransactions: JSON string containing array of subtransactions. Each subtransaction should have: - amount (required): The subtransaction amount - category_id (optional): Category ID for this split - payee_id (optional): Payee ID for this split - memo (optional): Memo for this split Example: '[{"amount": -50.00, "category_id": "cat1", "memo": "Groceries"}, {"amount": -30.00, "category_id": "cat2", "memo": "Gas"}]' payee_name: Name of the payee for the main transaction (optional) memo: Transaction memo (optional) cleared: Cleared status - 'cleared', 'uncleared', or 'reconciled' (default: 'uncleared') approved: Whether the transaction is approved (default: False) Returns: JSON string with the created split transaction Important Notes: - This creates a NEW transaction only - cannot modify existing transactions to add splits - The sum of subtransaction amounts should equal the total transaction amount - Once created, subtransactions cannot be modified via the API (YNAB limitation) - To "split" an existing transaction, you must delete it and create a new split transaction """ client = get_ynab_client() # Parse subtransactions JSON string try: subtransactions_list = json.loads(subtransactions) except json.JSONDecodeError as e: raise YNABValidationError(f"Invalid subtransactions JSON: {e}") from e result = await client.create_split_transaction( budget_id, account_id, date, amount, subtransactions_list, payee_name, memo, cleared, approved, ) return json.dumps(result, indent=2)
• src/ynab_mcp/ynab_client.py:1480-1588 (helper)

  Core implementation: formats subtransactions payload (converts amounts to milliunits, sets category_id=None on parent), POSTs to YNAB /transactions endpoint, formats response including subtransactions.
  async def create_split_transaction( self, budget_id: str, account_id: str, date: str, amount: float, subtransactions: list[dict[str, Any]], payee_name: str | None = None, memo: str | None = None, cleared: str = "uncleared", approved: bool = False, ) -> dict[str, Any]: """Create a new split transaction with subtransactions. Args: budget_id: The budget ID or 'last-used' account_id: The account ID for this transaction date: Transaction date in YYYY-MM-DD format amount: Total transaction amount (positive for inflow, negative for outflow) subtransactions: List of subtransaction dictionaries, each containing: - amount (float, required): Subtransaction amount - category_id (str, optional): Category ID for this subtransaction - payee_id (str, optional): Payee ID for this subtransaction - memo (str, optional): Memo for this subtransaction payee_name: Name of the payee for the main transaction (optional) memo: Transaction memo (optional) cleared: Cleared status - 'cleared', 'uncleared', or 'reconciled' (default: 'uncleared') approved: Whether the transaction is approved (default: False) Returns: JSON string with the created split transaction Note: - The sum of subtransaction amounts should equal the total transaction amount - category_id on the main transaction will be set to null automatically for split transactions """ try: url = f"{self.api_base_url}/budgets/{budget_id}/transactions" # Format subtransactions formatted_subtransactions = [] for sub in subtransactions: sub_data = { "amount": int(sub["amount"] * MILLIUNITS_FACTOR), } if sub.get("category_id"): sub_data["category_id"] = sub["category_id"] if sub.get("payee_id"): sub_data["payee_id"] = sub["payee_id"] if sub.get("memo"): sub_data["memo"] = sub["memo"] formatted_subtransactions.append(sub_data) # Build transaction data with subtransactions transaction_data = { "account_id": account_id, "date": date, "amount": int(amount * MILLIUNITS_FACTOR), "category_id": None, # Must be null for split transactions "subtransactions": formatted_subtransactions, "cleared": cleared, "approved": approved, } if payee_name is not None: transaction_data["payee_name"] = payee_name if memo is not None: transaction_data["memo"] = memo data = {"transaction": transaction_data} result = await self._make_request_with_retry("post", url, json=data) txn = result["data"]["transaction"] # Format subtransactions in response subtransactions_response = [] if txn.get("subtransactions"): for sub in txn["subtransactions"]: subtransactions_response.append( { "id": sub.get("id"), "amount": sub["amount"] / MILLIUNITS_FACTOR if sub.get("amount") else 0, "memo": sub.get("memo"), "payee_id": sub.get("payee_id"), "payee_name": sub.get("payee_name"), "category_id": sub.get("category_id"), "category_name": sub.get("category_name"), } ) return { "id": txn["id"], "date": txn["date"], "amount": txn["amount"] / MILLIUNITS_FACTOR if txn.get("amount") else 0, "memo": txn.get("memo"), "cleared": txn.get("cleared"), "approved": txn.get("approved"), "account_id": txn.get("account_id"), "account_name": txn.get("account_name"), "payee_id": txn.get("payee_id"), "payee_name": txn.get("payee_name"), "category_id": txn.get("category_id"), "category_name": txn.get("category_name"), "subtransactions": subtransactions_response, } except Exception as e: raise Exception(f"Failed to create split transaction: {e}") from e