lookup-payee-locations
Retrieve geographic locations linked to a payee in your YNAB budget. Use this tool to identify payee-specific locations by budget, payee, or location ID for precise financial tracking.
Instructions
Look up geographic locations associated with a payee.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | The ID of the budget. If not provided, the default budget will be used. | |
| location_id | No | The ID of a specific payee location to retrieve. | |
| payee_id | No | The ID of a payee to list locations for. |
Implementation Reference
- src/ynab_mcp_server/server.py:579-604 (handler)The handler for executing the 'lookup-payee-locations' tool. Validates arguments, fetches payee locations using ynab_client methods based on provided location_id or payee_id or all, formats and returns the results as text content.
elif name == "lookup-payee-locations": args = LookupPayeeLocationsInput.model_validate(arguments or {}) budget_id = await _get_budget_id(args.model_dump()) locations = [] if args.location_id: location = await ynab_client.get_payee_location_by_id( budget_id, args.location_id ) locations = [location] if location else [] elif args.payee_id: locations = await ynab_client.get_payee_locations_by_payee( budget_id, args.payee_id ) else: locations = await ynab_client.get_payee_locations(budget_id) if not locations: return [types.TextContent(type="text", text="No payee locations found.")] locations_dict = [loc.to_dict() for loc in locations] return [ types.TextContent( type="text", text=f"Found {len(locations)} payee locations:\n{json.dumps(locations_dict, indent=2, default=str)}", ) ] - Pydantic model defining the input schema for the tool, inheriting from BudgetIdInput. Supports optional location_id, payee_id, and budget_id.
class LookupPayeeLocationsInput(BudgetIdInput): location_id: Optional[str] = Field( None, description="The ID of a specific payee location to retrieve." ) payee_id: Optional[str] = Field( None, description="The ID of a payee to list locations for." ) - src/ynab_mcp_server/server.py:125-129 (registration)Registration of the tool in the list_tools handler, specifying name, description, and input schema reference.
types.Tool( name="lookup-payee-locations", description="Look up geographic locations associated with a payee.", inputSchema=LookupPayeeLocationsInput.model_json_schema(), ), - Helper method in YNABClient to fetch payee locations by payee ID, used by the tool handler.
async def get_payee_locations_by_payee( self, budget_id: str, payee_id: str ) -> list[ynab.PayeeLocation]: response = await self._run_sync( self._payee_locations_api.get_payee_locations_by_payee, budget_id, payee_id, ) return response.data.payee_locations - Helper method in YNABClient to fetch all payee locations for a budget, used by the tool handler.
async def get_payee_locations(self, budget_id: str) -> list[ynab.PayeeLocation]: response = await self._run_sync( self._payee_locations_api.get_payee_locations, budget_id ) return response.data.payee_locations - Helper method in YNABClient to fetch a specific payee location by ID, used by the tool handler.
async def get_payee_location_by_id( self, budget_id: str, payee_location_id: str ) -> ynab.PayeeLocation: response = await self._run_sync( self._payee_locations_api.get_payee_location_by_id, budget_id, payee_location_id, ) return response.data.payee_location