YNAB MCP Server

Instructions

This tool fetches an existing transaction's details and creates a new UNAPPROVED split
transaction with the same date, amount, account, and payee. You can then manually match
them together in the YNAB web or mobile UI.

Use this when you want to split an imported bank transaction - the new split will be
created as unapproved so you can match it with the original in YNAB's UI.

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    transaction_id: The ID of the existing transaction to split
    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"}]'

Returns:
    JSON string with original transaction details, new split transaction details, and instructions

Workflow:
    1. This tool fetches the existing transaction details
    2. Creates a new unapproved split transaction with those details
    3. You manually match them in the YNAB UI
    4. YNAB merges them into one split transaction

Note:
    - The new split is created as UNAPPROVED for manual matching
    - The sum of subtransaction amounts should equal the original transaction amount
    - After matching in YNAB UI, the original transaction will become a split transaction

Implementation Reference

• src/ynab_mcp/ynab_client.py:1589-1652 (handler)

  Core implementation of prepare_split_for_matching: fetches the original transaction, creates a duplicate unapproved split transaction with provided subtransactions for manual matching in YNAB UI, returns details of both with instructions.

  async def prepare_split_for_matching(
      self,
      budget_id: str,
      transaction_id: str,
      subtransactions: list[dict[str, Any]],
  ) -> dict[str, Any]:
      """Prepare a split transaction to match with an existing imported transaction.
  
      This fetches an existing transaction's details and creates a new unapproved split
      transaction with the same date, amount, account, and payee. You can then manually
      match them in the YNAB UI.
  
      Args:
          budget_id: The budget ID or 'last-used'
          transaction_id: The ID of the existing transaction to base the split on
          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
  
      Returns:
          Dictionary with original transaction details and newly created split transaction
  
      Note:
          - The new split transaction is created as unapproved
          - You must manually match them in the YNAB UI
          - The sum of subtransaction amounts should equal the original transaction amount
      """
      try:
          # Fetch the original transaction details
          original = await self.get_transaction(budget_id, transaction_id)
  
          # Create a new split transaction with the same details but unapproved
          new_split = await self.create_split_transaction(
              budget_id=budget_id,
              account_id=original["account_id"],
              date=original["date"],
              amount=original["amount"],
              subtransactions=subtransactions,
              payee_name=original.get("payee_name"),
              memo=original.get("memo"),
              cleared=original.get("cleared", "uncleared"),
              approved=False,  # Always create as unapproved for manual matching
          )
  
          return {
              "original_transaction": {
                  "id": original["id"],
                  "date": original["date"],
                  "amount": original["amount"],
                  "payee_name": original.get("payee_name"),
                  "account_name": original.get("account_name"),
              },
              "new_split_transaction": new_split,
              "instructions": (
                  "A new unapproved split transaction has been created. "
                  "Go to YNAB and manually match these two transactions together. "
                  "Look for the match indicator in the YNAB UI."
              ),
          }
      except Exception as e:
          raise Exception(f"Failed to prepare split for matching: {e}") from e

• src/ynab_mcp/server.py:591-642 (registration)

  MCP registration and wrapper handler: @mcp.tool() decorator registers the tool, function handles JSON input/output serialization and delegates to YNABClient method.

  @mcp.tool()
  async def prepare_split_for_matching(
      budget_id: str,
      transaction_id: str,
      subtransactions: str,
  ) -> str:
      """Prepare a split transaction to match with an existing imported transaction.
  
      This tool fetches an existing transaction's details and creates a new UNAPPROVED split
      transaction with the same date, amount, account, and payee. You can then manually match
      them together in the YNAB web or mobile UI.
  
      Use this when you want to split an imported bank transaction - the new split will be
      created as unapproved so you can match it with the original in YNAB's UI.
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          transaction_id: The ID of the existing transaction to split
          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"}]'
  
      Returns:
          JSON string with original transaction details, new split transaction details, and instructions
  
      Workflow:
          1. This tool fetches the existing transaction details
          2. Creates a new unapproved split transaction with those details
          3. You manually match them in the YNAB UI
          4. YNAB merges them into one split transaction
  
      Note:
          - The new split is created as UNAPPROVED for manual matching
          - The sum of subtransaction amounts should equal the original transaction amount
          - After matching in YNAB UI, the original transaction will become a 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.prepare_split_for_matching(
          budget_id, transaction_id, subtransactions_list
      )
      return json.dumps(result, indent=2)

• src/ynab_mcp/ynab_client.py:1480-1587 (helper)

  Supporting helper: create_split_transaction - used by prepare_split_for_matching to create the new split txn.

  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

• src/ynab_mcp/ynab_client.py:1425-1477 (helper)

  Supporting helper: get_transaction - used by prepare_split_for_matching to fetch original transaction details.

  async def get_transaction(
      self,
      budget_id: str,
      transaction_id: str,
  ) -> dict[str, Any]:
      """Get a single transaction with all details including subtransactions.
  
      Args:
          budget_id: The budget ID or 'last-used'
          transaction_id: The transaction ID to retrieve
  
      Returns:
          Transaction dictionary with full details
      """
      try:
          url = f"{self.api_base_url}/budgets/{budget_id}/transactions/{transaction_id}"
          result = await self._make_request_with_retry("get", url)
  
          txn = result["data"]["transaction"]
  
          # Format subtransactions if present
          subtransactions = []
          if txn.get("subtransactions"):
              for sub in txn["subtransactions"]:
                  subtransactions.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"),
              "transfer_account_id": txn.get("transfer_account_id"),
              "subtransactions": subtransactions if subtransactions else None,
          }
      except Exception as e: