MCP YNAB Server

Instructions

Implementation Reference

• src/mcp_ynab/server.py:382-414 (handler)

  The primary handler function for the 'get_accounts' tool. It takes a budget_id, fetches accounts using the YNAB AccountsApi, formats the output using _format_accounts_output, builds a Markdown summary with grouped accounts, totals, and tables.
  @mcp.tool() async def get_accounts(budget_id: str) -> str: """List all YNAB accounts in a specific budget in Markdown format.""" async with await get_ynab_client() as client: accounts_api = AccountsApi(client) all_accounts: List[Dict[str, Any]] = [] response = accounts_api.get_accounts(budget_id) for account in response.data.accounts: if isinstance(account, Account): all_accounts.append(account.to_dict()) formatted = _format_accounts_output(all_accounts) markdown = "# YNAB Account Summary\n\n" markdown += "## Summary\n" markdown += f"- **Total Assets:** {formatted['summary']['total_assets']}\n" markdown += f"- **Total Liabilities:** {formatted['summary']['total_liabilities']}\n" markdown += f"- **Net Worth:** {formatted['summary']['net_worth']}\n\n" for group in formatted["accounts"]: markdown += f"## {group['type']}\n" markdown += f"**Group Total:** {group['total']}\n\n" rows = [] for acct in group["accounts"]: rows.append([acct["name"], acct["balance"], acct["id"]]) markdown += _build_markdown_table( rows, ["Account Name", "Balance", "ID"], ["left", "right", "left"] ) markdown += "\n" return markdown
• src/mcp_ynab/server.py:118-202 (helper)

  Helper function _format_accounts_output that processes account data: groups by type (checking, savings, etc.), calculates balances in dollars, sorts by balance, computes assets/liabilities/net worth summary, excludes closed/deleted accounts.
  def _format_accounts_output(accounts: List[Dict[str, Any]]) -> Dict[str, Any]: """Format account data into a user-friendly structure.""" account_groups: Dict[str, List[Dict[str, Any]]] = {} type_order = [ "checking", "savings", "creditCard", "mortgage", "autoLoan", "studentLoan", "otherAsset", "otherLiability", ] type_display_names = { "checking": "Checking Accounts", "savings": "Savings Accounts", "creditCard": "Credit Cards", "mortgage": "Mortgages", "autoLoan": "Auto Loans", "studentLoan": "Student Loans", "otherAsset": "Other Assets", "otherLiability": "Other Liabilities", } for account in accounts: if account.get("closed", False) or account.get("deleted", False): continue acct_type = account["type"] if acct_type not in account_groups: account_groups[acct_type] = [] balance = float(account["balance"]) / 1000 account_groups[acct_type].append( { "name": account["name"], "balance": f"${balance:,.2f}", "balance_raw": balance, "id": account["id"], } ) for group in account_groups.values(): group.sort(key=lambda x: abs(x["balance_raw"]), reverse=True) output: Dict[str, Any] = { "accounts": [], "summary": { "total_assets": 0.0, "total_liabilities": 0.0, "net_worth": 0.0, }, } for acct_type in type_order: if acct_type in account_groups and account_groups[acct_type]: group_data = { "type": type_display_names.get(acct_type, acct_type), "accounts": account_groups[acct_type], } group_total = sum(acct["balance_raw"] for acct in account_groups[acct_type]) group_data["total"] = f"${group_total:,.2f}" if acct_type in ["checking", "savings", "otherAsset"]: output["summary"]["total_assets"] += group_total elif acct_type in [ "creditCard", "mortgage", "autoLoan", "studentLoan", "otherLiability", ]: output["summary"]["total_liabilities"] += abs(group_total) output["accounts"].append(group_data) output["summary"]["net_worth_raw"] = ( output["summary"]["total_assets"] - output["summary"]["total_liabilities"] ) output["summary"]["total_assets"] = f"${output['summary']['total_assets']:,.2f}" output["summary"]["total_liabilities"] = f"${output['summary']['total_liabilities']:,.2f}" output["summary"]["net_worth"] = f"${output['summary']['net_worth_raw']:,.2f}" return output
• src/mcp_ynab/server.py:382-382 (registration)

  The @mcp.tool() decorator registers the get_accounts function as an MCP tool.
  @mcp.tool()