Skip to content

Resources API

Auto-generated API reference for MCP resource functions. Resources are split between static knowledge content (YNAB methodology) and dynamic budget data (live from the YNAB API).

Knowledge Resources

Static YNAB methodology content loaded from markdown files at import time.

knowledge

MCP Resource definitions for YNAB methodology knowledge.

Exposes static YNAB budgeting knowledge as MCP Resources at ynab://knowledge/ URIs. LLMs can read these resources to understand YNAB methodology without hallucinating concepts.

All resources return markdown content loaded at import time from the methodology/ subpackage.

mcp module-attribute 

mcp = FastMCP('YNAB', lifespan=lifespan)

_methodology module-attribute 

_methodology = files('ynaa_mcp.methodology')

TERMINOLOGY_CONTENT module-attribute 

TERMINOLOGY_CONTENT = read_text(encoding='utf-8')

CREDIT_CARDS_CONTENT module-attribute 

CREDIT_CARDS_CONTENT = read_text(encoding='utf-8')

GOALS_CONTENT module-attribute 

GOALS_CONTENT = read_text(encoding='utf-8')

OVERSPENDING_CONTENT module-attribute 

OVERSPENDING_CONTENT = read_text(encoding='utf-8')

RECONCILIATION_CONTENT module-attribute 

RECONCILIATION_CONTENT = read_text(encoding='utf-8')

terminology 

terminology() -> str

YNAB terminology and key concepts reference.

Covers milliunits, on-budget vs off-budget accounts, age of money, To Be Budgeted, the Four Rules, and transaction states.

Returns:

  • str –

    Markdown content explaining YNAB terminology.

Source code in src/ynaa_mcp/knowledge.py 
33
34
35
36
37
38
39
40
41
42
43
44
@mcp.resource("ynab://knowledge/terminology", mime_type="text/markdown")
def terminology() -> str:
    """YNAB terminology and key concepts reference.

    Covers milliunits, on-budget vs off-budget accounts,
    age of money, To Be Budgeted, the Four Rules, and
    transaction states.

    Returns:
        Markdown content explaining YNAB terminology.
    """
    return TERMINOLOGY_CONTENT

credit_cards 

credit_cards() -> str

YNAB credit card handling guide.

Covers the Credit Card Payment category, budgeting for purchases on credit, making payments, returns and refunds, pre-YNAB debt, and common mistakes.

Returns:

  • str –

    Markdown content explaining credit card handling in YNAB.

Source code in src/ynaa_mcp/knowledge.py 
47
48
49
50
51
52
53
54
55
56
57
58
@mcp.resource("ynab://knowledge/credit-cards", mime_type="text/markdown")
def credit_cards() -> str:
    """YNAB credit card handling guide.

    Covers the Credit Card Payment category, budgeting for
    purchases on credit, making payments, returns and refunds,
    pre-YNAB debt, and common mistakes.

    Returns:
        Markdown content explaining credit card handling in YNAB.
    """
    return CREDIT_CARDS_CONTENT

goals 

goals() -> str

YNAB goal types reference.

Covers Target Category Balance, Monthly Savings Builder, Needed for Spending goal types with API field mappings and use case guidance.

Returns:

  • str –

    Markdown content explaining YNAB goal types.

Source code in src/ynaa_mcp/knowledge.py 
61
62
63
64
65
66
67
68
69
70
71
72
@mcp.resource("ynab://knowledge/goals", mime_type="text/markdown")
def goals() -> str:
    """YNAB goal types reference.

    Covers Target Category Balance, Monthly Savings Builder,
    Needed for Spending goal types with API field mappings
    and use case guidance.

    Returns:
        Markdown content explaining YNAB goal types.
    """
    return GOALS_CONTENT

overspending 

overspending() -> str

YNAB overspending behavior guide.

Covers cash vs credit overspending, negative balance rollover behavior, and strategies for handling overspent categories.

Returns:

  • str –

    Markdown content explaining overspending in YNAB.

Source code in src/ynaa_mcp/knowledge.py 
75
76
77
78
79
80
81
82
83
84
85
86
@mcp.resource("ynab://knowledge/overspending", mime_type="text/markdown")
def overspending() -> str:
    """YNAB overspending behavior guide.

    Covers cash vs credit overspending, negative balance
    rollover behavior, and strategies for handling
    overspent categories.

    Returns:
        Markdown content explaining overspending in YNAB.
    """
    return OVERSPENDING_CONTENT

reconciliation 

reconciliation() -> str

YNAB reconciliation process guide.

Covers the step-by-step reconciliation process, transaction statuses, adjustment transactions, and best practices for regular reconciliation.

Returns:

  • str –

    Markdown content explaining reconciliation in YNAB.

Source code in src/ynaa_mcp/knowledge.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@mcp.resource("ynab://knowledge/reconciliation", mime_type="text/markdown")
def reconciliation() -> str:
    """YNAB reconciliation process guide.

    Covers the step-by-step reconciliation process,
    transaction statuses, adjustment transactions,
    and best practices for regular reconciliation.

    Returns:
        Markdown content explaining reconciliation in YNAB.
    """
    return RECONCILIATION_CONTENT

Budget Resources

Dynamic resources that fetch live data from the YNAB API for a specific budget.

resources

MCP Resource definitions for YNAB budget structure.

Exposes budget accounts, categories, and payees as MCP Resources at ynab:// URIs. LLMs can read these resources upfront to understand budget structure without repeated tool calls.

All resources return JSON strings with filtered, current data. Deleted entities are always excluded. Categories also exclude hidden items, and payees exclude transfer payees.

mcp module-attribute 

mcp = FastMCP('YNAB', lifespan=lifespan)

AppContext dataclass 

AppContext(client: YNABClient, cache: CacheStore)

Shared dependencies for all MCP tools.

Created during server lifespan and available to tools via ctx.lifespan_context.

Attributes:

  • client (YNABClient) –

    The YNAB API client instance.

  • cache (CacheStore) –

    The delta cache store for YNAB API responses.

budget_accounts async 

budget_accounts(budget_id: str, ctx: Context) -> str

List all active accounts in a budget with current balances.

Returns a JSON array of non-deleted accounts, each containing id, name, type, on_budget, closed, and balance fields.

Parameters:

  • budget_id (str) –

    The YNAB budget ID.

  • ctx (Context) –

    The MCP context with lifespan dependencies.

Returns:

  • str –

    JSON string of account objects.

Source code in src/ynaa_mcp/resources.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
@mcp.resource("ynab://budgets/{budget_id}/accounts")
async def budget_accounts(budget_id: str, ctx: Context) -> str:
    """List all active accounts in a budget with current balances.

    Returns a JSON array of non-deleted accounts, each containing
    id, name, type, on_budget, closed, and balance fields.

    Args:
        budget_id: The YNAB budget ID.
        ctx: The MCP context with lifespan dependencies.

    Returns:
        JSON string of account objects.
    """
    app = cast("AppContext", ctx.lifespan_context)
    data: dict[str, Any] = await app.client.get(
        f"/budgets/{budget_id}/accounts",
    )

    accounts = [
        {
            "id": acct["id"],
            "name": acct["name"],
            "type": acct["type"],
            "on_budget": acct["on_budget"],
            "closed": acct["closed"],
            "balance": acct["balance"],
        }
        for acct in data["accounts"]
        if not acct["deleted"]
    ]

    return json.dumps(accounts, indent=2)

budget_categories async 

budget_categories(budget_id: str, ctx: Context) -> str

List all active category groups and categories with budget amounts.

Returns a JSON array of non-deleted category groups, each containing a group name and nested array of non-deleted, non-hidden categories with id, name, budgeted, activity, and balance fields.

Groups with no visible categories after filtering are excluded.

Parameters:

  • budget_id (str) –

    The YNAB budget ID.

  • ctx (Context) –

    The MCP context with lifespan dependencies.

Returns:

  • str –

    JSON string of category group objects.

Source code in src/ynaa_mcp/resources.py 
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@mcp.resource("ynab://budgets/{budget_id}/categories")
async def budget_categories(budget_id: str, ctx: Context) -> str:
    """List all active category groups and categories with budget amounts.

    Returns a JSON array of non-deleted category groups, each containing
    a group name and nested array of non-deleted, non-hidden categories
    with id, name, budgeted, activity, and balance fields.

    Groups with no visible categories after filtering are excluded.

    Args:
        budget_id: The YNAB budget ID.
        ctx: The MCP context with lifespan dependencies.

    Returns:
        JSON string of category group objects.
    """
    app = cast("AppContext", ctx.lifespan_context)
    data: dict[str, Any] = await app.client.get(
        f"/budgets/{budget_id}/categories",
    )

    groups: list[dict[str, Any]] = []
    for group in data["category_groups"]:
        if group["deleted"]:
            continue

        visible_cats = [
            {
                "id": cat["id"],
                "name": cat["name"],
                "budgeted": cat["budgeted"],
                "activity": cat["activity"],
                "balance": cat["balance"],
            }
            for cat in group["categories"]
            if not cat["deleted"] and not cat["hidden"]
        ]

        if visible_cats:
            groups.append({
                "group": group["name"],
                "categories": visible_cats,
            })

    return json.dumps(groups, indent=2)

budget_payees async 

budget_payees(budget_id: str, ctx: Context) -> str

List all non-transfer payees in a budget.

Returns a JSON array of non-deleted, non-transfer payees with id and name fields. Transfer payees (those linked to an account) are excluded.

Parameters:

  • budget_id (str) –

    The YNAB budget ID.

  • ctx (Context) –

    The MCP context with lifespan dependencies.

Returns:

  • str –

    JSON string of payee objects.

Source code in src/ynaa_mcp/resources.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@mcp.resource("ynab://budgets/{budget_id}/payees")
async def budget_payees(budget_id: str, ctx: Context) -> str:
    """List all non-transfer payees in a budget.

    Returns a JSON array of non-deleted, non-transfer payees with
    id and name fields. Transfer payees (those linked to an account)
    are excluded.

    Args:
        budget_id: The YNAB budget ID.
        ctx: The MCP context with lifespan dependencies.

    Returns:
        JSON string of payee objects.
    """
    app = cast("AppContext", ctx.lifespan_context)
    data: dict[str, Any] = await app.client.get(
        f"/budgets/{budget_id}/payees",
    )

    payees = [
        {
            "id": payee["id"],
            "name": payee["name"],
        }
        for payee in data["payees"]
        if not payee["deleted"] and payee.get("transfer_account_id") is None
    ]

    return json.dumps(payees, indent=2)