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()