YNAB MCP Server

Instructions

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    search_term: Text to search for in payee name or memo (case-insensitive)
    since_date: Only search transactions on or after this date (YYYY-MM-DD format)
    until_date: Only search transactions on or before this date (YYYY-MM-DD format)
    limit: Maximum number of transactions to return (default: 100, max: 500)

Returns:
    JSON string with matching transactions and count

Implementation Reference

• src/ynab_mcp/server.py:176-198 (handler)

  MCP tool handler for search_transactions. Registers the tool with @mcp.tool() decorator and implements the execution logic by delegating to YNABClient and returning JSON.

  @mcp.tool()
  async def search_transactions(
      budget_id: str,
      search_term: str,
      since_date: str = None,
      until_date: str = None,
      limit: int = None,
  ) -> str:
      """Search for transactions by text in payee name or memo.
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          search_term: Text to search for in payee name or memo (case-insensitive)
          since_date: Only search transactions on or after this date (YYYY-MM-DD format)
          until_date: Only search transactions on or before this date (YYYY-MM-DD format)
          limit: Maximum number of transactions to return (default: 100, max: 500)
  
      Returns:
          JSON string with matching transactions and count
      """
      client = get_ynab_client()
      result = await client.search_transactions(budget_id, search_term, since_date, until_date, limit)
      return json.dumps(result, indent=2)

• src/ynab_mcp/ynab_client.py:630-702 (helper)

  Core implementation of transaction search in YNABClient class. Fetches transactions from YNAB API, performs case-insensitive search on payee_name and memo, applies date and limit filters, formats results.

  async def search_transactions(
      self,
      budget_id: str,
      search_term: str,
      since_date: str | None = None,
      until_date: str | None = None,
      limit: int | None = None,
  ) -> dict[str, Any]:
      """Search transactions by text matching in payee name or memo.
  
      Args:
          budget_id: The budget ID or 'last-used'
          search_term: Text to search for in payee name or memo (case-insensitive)
          since_date: Only return transactions on or after this date (YYYY-MM-DD)
          until_date: Only return transactions on or before this date (YYYY-MM-DD)
          limit: Maximum number of transactions to return (default: 100, max: 500)
  
      Returns:
          Dictionary with matching transactions and count
      """
      try:
          # Get all transactions with date filtering
          url = f"{self.api_base_url}/budgets/{budget_id}/transactions"
          params = {}
          if since_date:
              params["since_date"] = since_date
  
          result = await self._make_request_with_retry("get", url, params=params)
  
          txn_data = result["data"]["transactions"]
  
          # Search and filter
          search_lower = search_term.lower()
          matching_transactions = []
  
          for txn in txn_data:
              # Filter by until_date if provided
              if until_date and txn["date"] > until_date:
                  continue
  
              # Search in payee_name and memo
              payee_name = (txn.get("payee_name") or "").lower()
              memo = (txn.get("memo") or "").lower()
  
              if search_lower in payee_name or search_lower in memo:
                  matching_transactions.append(
                      {
                          "id": txn["id"],
                          "date": txn["date"],
                          "amount": txn["amount"] / 1000 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"),
                      }
                  )
  
                  # Apply limit if specified
                  if limit and len(matching_transactions) >= limit:
                      break
  
          return {
              "search_term": search_term,
              "transactions": matching_transactions,
              "count": len(matching_transactions),
          }
      except Exception as e:
          raise Exception(f"Failed to search transactions: {e}") from e

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

  The @mcp.tool() decorator registers 'search_transactions' as an MCP tool, defining its input schema from the function signature and docstring.

  @mcp.tool()
  async def search_transactions(
      budget_id: str,
      search_term: str,
      since_date: str = None,
      until_date: str = None,
      limit: int = None,
  ) -> str:
      """Search for transactions by text in payee name or memo.
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          search_term: Text to search for in payee name or memo (case-insensitive)
          since_date: Only search transactions on or after this date (YYYY-MM-DD format)
          until_date: Only search transactions on or before this date (YYYY-MM-DD format)
          limit: Maximum number of transactions to return (default: 100, max: 500)
  
      Returns:
          JSON string with matching transactions and count
      """
      client = get_ynab_client()
      result = await client.search_transactions(budget_id, search_term, since_date, until_date, limit)
      return json.dumps(result, indent=2)