Payee Tools¶

Payees are the people and businesses you exchange money with -- your landlord, the grocery store, your employer. Payee tools let you browse your payee list, view details, rename payees for consistency, and check payee locations. Clean payee names make your transaction history easier to read and your reports more meaningful.

YNAB automatically creates payees from imported transactions, which can lead to inconsistencies (like "AMAZON.COM" and "Amazon" as separate payees). Renaming helps you keep things tidy.

Usage Examples¶

You: Show me my payees.

Claude calls manage_payees with action list and responds:

47 payees found: - Amazon - Chipotle - Electric Company - Employer Inc - Whole Foods ...

You: I want to see transfer payees too.

Claude calls manage_payees with action list and include_transfers=true:

52 payees found (including transfers): - Amazon - Transfer : Checking - Transfer : Savings ...

You: Rename "AMZN MKTP" to "Amazon".

Claude calls manage_payees with action update_name:

Payee renamed: "AMZN MKTP" is now "Amazon"

You: Does Whole Foods have a location on file?

Claude calls manage_payees with action get_location and responds:

Whole Foods -- Location: Latitude: 40.7128, Longitude: -74.0060

Available Actions¶

Action	Description
`list`	List all payees (optionally include transfers)
`get`	Get details for a specific payee
`update_name`	Rename a payee
`list_locations`	List all payee locations
`get_location`	Get location details for a specific payee

API Reference¶

manage_payees `async` ¶

manage_payees(
    ctx: Context,
    action: Literal["list", "get", "update_name", "list_locations", "get_location"],
    budget_id_or_name: str = "last-used",
    include_transfers: bool = False,
    payee_id: str | None = None,
    name: str | None = None,
    payee_location_id: str | None = None,
) -> str

Manage YNAB payees: list, get details, rename, and query locations.

Actions

list: List all payees. Uses budget_id_or_name, include_transfers. get: Get payee details. Uses payee_id (required). update_name: Rename payee. Uses payee_id (required), name (required). list_locations: List payee locations. Uses payee_id (optional filter). get_location: Get location details. Uses payee_location_id (required).

Parameters:

ctx (Context) –

The MCP context providing access to lifespan dependencies.
action (Literal['list', 'get', 'update_name', 'list_locations', 'get_location']) –

The operation to perform.
budget_id_or_name (str, default: 'last-used' ) –

Budget UUID or name. Defaults to "last-used".
include_transfers (bool, default: False ) –

If True, include transfer payees (list only).
payee_id (str | None, default: None ) –

The payee UUID (get, update_name, list_locations).
name (str | None, default: None ) –

New name for the payee (update_name only).
payee_location_id (str | None, default: None ) –

The payee location UUID (get_location only).

Returns:

str –

Structured text with payee information or confirmation.

Raises:

ToolError –

If required parameters for the action are missing.

Source code in src/ynaa_mcp/tools/payees.py

@mcp.tool
async def manage_payees(  # noqa: PLR0913, PLR0917
    ctx: Context,
    action: Literal["list", "get", "update_name", "list_locations", "get_location"],
    budget_id_or_name: str = "last-used",
    include_transfers: bool = False,  # noqa: FBT001, FBT002
    payee_id: str | None = None,
    name: str | None = None,
    payee_location_id: str | None = None,
) -> str:
    """Manage YNAB payees: list, get details, rename, and query locations.

    Actions:
        list: List all payees. Uses budget_id_or_name, include_transfers.
        get: Get payee details. Uses payee_id (required).
        update_name: Rename payee. Uses payee_id (required), name (required).
        list_locations: List payee locations. Uses payee_id (optional filter).
        get_location: Get location details. Uses payee_location_id (required).

    Args:
        ctx: The MCP context providing access to lifespan dependencies.
        action: The operation to perform.
        budget_id_or_name: Budget UUID or name. Defaults to "last-used".
        include_transfers: If True, include transfer payees (list only).
        payee_id: The payee UUID (get, update_name, list_locations).
        name: New name for the payee (update_name only).
        payee_location_id: The payee location UUID (get_location only).

    Returns:
        Structured text with payee information or confirmation.

    Raises:
        ToolError: If required parameters for the action are missing.
    """
    app = cast("AppContext", ctx.lifespan_context)
    budget_id, _info = await resolve_budget(
        app.client, budget_id_or_name, cache=app.cache
    )

    if action == "list":
        return await _list_payees(app, budget_id, include_transfers=include_transfers)
    if action == "get":
        if payee_id is None:
            msg = "payee_id is required for action='get'"
            raise ToolError(msg)
        return await _get_payee(app, budget_id, payee_id=payee_id)
    if action == "update_name":
        if payee_id is None or name is None:
            msg = "payee_id and name are required for action='update_name'"
            raise ToolError(msg)
        return await _update_name(app, budget_id, payee_id=payee_id, name=name)
    if action == "list_locations":
        return await _list_locations(app, budget_id, payee_id=payee_id)
    if payee_location_id is None:
        msg = "payee_location_id is required for action='get_location'"
        raise ToolError(msg)
    return await _get_location(app, budget_id, payee_location_id=payee_location_id)

Payee Tools¶

Usage Examples¶

Available Actions¶

API Reference¶

manage_payees async ¶

manage_payees `async` ¶