Account Tools¶

Accounts are where your money lives -- checking, savings, credit cards, cash, investment tracking, and more. Account tools let you see your balances at a glance, drill into individual account details, and create new accounts without leaving the conversation.

In YNAB, accounts fall into two categories: on-budget accounts (checking, savings, credit cards) where every dollar gets a job, and tracking accounts (investments, mortgages) that you monitor but don't budget from. This distinction matters when you're looking at your overall financial picture versus your day-to-day budget.

Usage Examples¶

You: Show me my accounts.

Claude calls manage_accounts with action list and responds:

4 open accounts found: - Checking (checking) -- Balance: $2,450.00 - Savings (savings) -- Balance: $8,200.00 - Visa (creditCard) -- Balance: -$1,340.00 - Cash (cash) -- Balance: $45.00

You: Tell me about my Visa account.

Claude calls manage_accounts with action get and responds:

Account: Visa Type: creditCard On budget: Yes Balance: -$1,340.00 Cleared balance: -$1,200.00 Uncleared balance: -$140.00

You: I want to include closed accounts too.

Claude calls manage_accounts with action list and include_closed=true:

6 accounts found (including closed): - Checking (checking) -- Balance: $2,450.00 - Old Savings (savings) -- Balance: $0.00 [closed] ...

You: Create a new savings account called Emergency Fund with $1,000.

Claude calls manage_accounts with action create, converting dollars to YNAB milliunits automatically:

Account created: Emergency Fund Type: savings Starting balance: $1,000.00

Available Actions¶

Action	Description
`list`	List all accounts in a budget (open by default, optionally closed)
`get`	Get detailed info about a specific account
`create`	Create a new account with a name, type, and starting balance

API Reference¶

manage_accounts `async` ¶

manage_accounts(
    ctx: Context,
    action: Literal["list", "get", "create"],
    budget_id_or_name: str | None = None,
    include_closed: bool = False,
    account_id: str | None = None,
    name: str | None = None,
    account_type: str | None = None,
    balance: float | None = None,
) -> str

Manage YNAB accounts: list, get details, or create.

Actions

list: List all accounts. Uses budget_id_or_name, include_closed. get: Get account details. Uses budget_id_or_name, account_id (required). create: Create account. Uses budget_id_or_name, name (required), account_type (required), balance (required).

Parameters:

ctx (Context) –

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

The operation to perform.
budget_id_or_name (str | None, default: None ) –

Budget UUID or name. Auto-resolves if only one budget exists.
include_closed (bool, default: False ) –

If True, include closed accounts (list only).
account_id (str | None, default: None ) –

The account UUID (get only).
name (str | None, default: None ) –

Display name for the new account (create only).
account_type (str | None, default: None ) –

Account type (create only).
balance (float | None, default: None ) –

Opening balance in dollars (create only).

Returns:

str –

Structured text with account information or confirmation.

Raises:

ToolError –

If required parameters for the action are missing.

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

@mcp.tool
async def manage_accounts(  # noqa: PLR0913, PLR0917
    ctx: Context,
    action: Literal["list", "get", "create"],
    budget_id_or_name: str | None = None,
    include_closed: bool = False,  # noqa: FBT001, FBT002
    account_id: str | None = None,
    name: str | None = None,
    account_type: str | None = None,
    balance: float | None = None,
) -> str:
    """Manage YNAB accounts: list, get details, or create.

    Actions:
        list: List all accounts. Uses budget_id_or_name, include_closed.
        get: Get account details. Uses budget_id_or_name, account_id (required).
        create: Create account. Uses budget_id_or_name, name (required),
            account_type (required), balance (required).

    Args:
        ctx: The MCP context providing access to lifespan dependencies.
        action: The operation to perform.
        budget_id_or_name: Budget UUID or name. Auto-resolves if only
            one budget exists.
        include_closed: If True, include closed accounts (list only).
        account_id: The account UUID (get only).
        name: Display name for the new account (create only).
        account_type: Account type (create only).
        balance: Opening balance in dollars (create only).

    Returns:
        Structured text with account 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_accounts(app, budget_id, info, include_closed=include_closed)

    if action == "get":
        if account_id is None:
            msg = "account_id is required for action='get'"
            raise ToolError(msg)
        return await _get_account(app, budget_id, info, account_id=account_id)

    if name is None or account_type is None or balance is None:
        msg = "name, account_type, and balance are required for action='create'"
        raise ToolError(msg)
    return await _create_account(
        app, budget_id, info, name=name, account_type=account_type, balance=balance
    )

Account Tools¶

Usage Examples¶

Available Actions¶

API Reference¶

manage_accounts async ¶

manage_accounts `async` ¶