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
`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)}",
        )
    ]

src/ynab_mcp_server/tool_models.py:342-348 (schema)

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(),
),

src/ynab_mcp_server/ynab_client.py:382-390 (helper)

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

src/ynab_mcp_server/ynab_client.py:366-370 (helper)

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

src/ynab_mcp_server/ynab_client.py:372-380 (helper)

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

You Need A Budget (YNAB) MCP