YNAB MCP Server

Instructions

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)