Budget Tools¶

Your budget is the foundation of everything in YNAB. Budget tools give you a bird's-eye view of your financial world -- listing your budgets, checking their details, and verifying your YNAB account info. Whether you manage one household budget or separate budgets for different goals, these tools are your starting point.

Most other tools need to know which budget to work with. If you only have one, it's selected automatically. If you have multiple, Claude will ask or match by name.

Budget Resolution

When you say something like "show me my Groceries category", the server needs to know which budget to look in. Here's how it works:

One budget? It's selected automatically -- you never need to specify it.
Multiple budgets? Claude will try to match by name (fuzzy matching), or ask you to clarify.
last-used shortcut: Most tools default to last-used, which picks the budget from YNAB's "last used" setting.

This means most conversations just work without you ever thinking about budget selection.

Usage Examples¶

You: Show me my budgets.

Claude calls manage_budgets with action list and responds:

2 budgets found: - My Budget (Last modified: 2026-03-01) - Vacation Fund (Last modified: 2026-02-15)

You: What's in my main budget?

Claude calls manage_budgets with action get and fuzzy name matching:

Budget: My Budget First month: 2024-01-01 Last month: 2026-04-01 Currency: USD Date format: MM/DD/YYYY

You: What YNAB account am I using?

Claude calls manage_budgets with action get_user and responds:

User: jane@example.com ID: abc123-def456

You: Tell me about my Vacation Fund budget.

Claude calls manage_budgets with action get and name matching:

Budget: Vacation Fund First month: 2025-06-01 Last month: 2026-06-01 Currency: USD Number of accounts: 2 Number of categories: 8

This budget has 12 months of history.

New to MCP?

These tools are called by Claude automatically when you ask budget-related questions. You never need to remember tool names or parameters -- just describe what you want in plain English.

Budget resolution is automatic too: if you only have one budget, tools use it without asking. If you have multiple budgets, Claude will ask which one you mean or match by name.

Available Actions¶

Action	Description
`list`	List all budgets on your YNAB account
`get`	Get detailed info about a specific budget
`get_user`	Get your YNAB user/account info

Common Patterns¶

Starting a conversation: Most budget conversations begin with "show me my budgets" or "how's my budget doing?" -- Claude will list budgets or get details for your default budget.

Multiple budgets: If you maintain separate budgets (e.g., personal and business, or a vacation fund), you can refer to them by name. Claude uses fuzzy matching, so "vacation" will match "Vacation Fund".

Budget details: The get action returns metadata like date range, currency, and format settings. For actual spending data, use Month Tools. For account balances, use Account Tools.

API Reference¶

manage_budgets `async` ¶

manage_budgets(
    ctx: Context,
    action: Literal["list", "get", "get_user"],
    budget_id_or_name: str | None = None,
) -> str

Manage YNAB budgets: list all, get details, or get user info.

Actions

list: List all budgets. No extra params needed. get: Get budget details. Uses budget_id_or_name. get_user: Get authenticated user info. No extra params needed.

Parameters:

ctx (Context) –

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

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

Budget UUID or name (get only). Auto-resolves if only one budget exists.

Returns:

str –

Structured text with budget or user information.

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

@mcp.tool
async def manage_budgets(
    ctx: Context,
    action: Literal["list", "get", "get_user"],
    budget_id_or_name: str | None = None,
) -> str:
    """Manage YNAB budgets: list all, get details, or get user info.

    Actions:
        list: List all budgets. No extra params needed.
        get: Get budget details. Uses budget_id_or_name.
        get_user: Get authenticated user info. No extra params needed.

    Args:
        ctx: The MCP context providing access to lifespan dependencies.
        action: The operation to perform.
        budget_id_or_name: Budget UUID or name (get only). Auto-resolves
            if only one budget exists.

    Returns:
        Structured text with budget or user information.
    """
    app = cast("AppContext", ctx.lifespan_context)

    if action == "list":
        return await _list_budgets(app)

    if action == "get":
        budget_id, info = await resolve_budget(
            app.client, budget_id_or_name, cache=app.cache
        )
        return await _get_budget(app, budget_id, info)

    return await _get_user(app)