YNAB MCP Server

Instructions

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    transaction_id: The ID of the transaction to retrieve

Returns:
    JSON string with the transaction details including subtransactions if it's a split transaction

Implementation Reference

• src/ynab_mcp/server.py:511-524 (handler)

  MCP tool handler function registered with @mcp.tool(). Wraps YNABClient.get_transaction and serializes result to JSON string.

  @mcp.tool()
  async def get_transaction(budget_id: str, transaction_id: str) -> str:
      """Get a single transaction with all details including subtransactions.
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          transaction_id: The ID of the transaction to retrieve
  
      Returns:
          JSON string with the transaction details including subtransactions if it's a split transaction
      """
      client = get_ynab_client()
      result = await client.get_transaction(budget_id, transaction_id)
      return json.dumps(result, indent=2)

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

  Supporting method in YNABClient that performs the actual API call to retrieve a single transaction by ID, formats response including subtransactions, and handles errors.

  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:
          raise Exception(f"Failed to get transaction: {e}") from e

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

  @mcp.tool() decorator registers the get_transaction function as an MCP tool.

  @mcp.tool()