You Need A Budget (YNAB) MCP

Instructions

Implementation Reference

• src/ynab_mcp_server/server.py:432-484 (handler)

  Executes the tool logic: get current overview from notes, update sections, or refresh with current account balances and categorized budgeted amounts.

  elif name == "manage-financial-overview":
      args = ManageFinancialOverviewInput.model_validate(arguments or {})
      
      if args.action == "get":
          overview = ynab_client.notes.load_overview()
          return [
              types.TextContent(
                  type="text",
                  text=f"Financial Overview (Last Updated: {overview.get('last_updated', 'Never')}):\n\n"
                       f"{json.dumps(overview, indent=2)}",
              )
          ]
      elif args.action == "update":
          ynab_client.notes.update_overview_section(args.section, args.data)
          return [
              types.TextContent(
                  type="text",
                  text=f"Successfully updated the {args.section} section of the financial overview.",
              )
          ]
      elif args.action == "refresh":
          budget_id = await _get_budget_id(args.model_dump())
          accounts = await ynab_client.get_accounts(budget_id=budget_id)
          account_balances = {
              acc.name: acc.balance / 1000
              for acc in accounts
          }
          categories = await ynab_client.get_categories(budget_id=budget_id)
          fixed_bills, discretionary_spending, savings = 0, 0, 0
          for group in categories:
              if "bills" in group.name.lower():
                  fixed_bills = sum(cat.budgeted for cat in group.categories if not cat.hidden)
              elif "wants" in group.name.lower() or "spending" in group.name.lower():
                  discretionary_spending = sum(cat.budgeted for cat in group.categories if not cat.hidden)
              elif "savings" in group.name.lower():
                  savings = sum(cat.budgeted for cat in group.categories if not cat.hidden)
          total_budgeted = fixed_bills + discretionary_spending + savings
          savings_rate = (savings / total_budgeted * 100) if total_budgeted > 0 else 0
          overview = ynab_client.notes.load_overview()
          overview["account_balances"] = account_balances
          overview["monthly_overview"] = {
              "fixed_bills": fixed_bills / 1000,
              "discretionary_spending": discretionary_spending / 1000,
              "savings_rate": savings_rate
          }
          ynab_client.notes.save_overview(overview)
          return [
              types.TextContent(
                  type="text",
                  text="Successfully refreshed the financial overview with latest YNAB data.",
              )
          ]
  elif name == "manage-scheduled-transaction":

• src/ynab_mcp_server/tool_models.py:14-37 (schema)

  Pydantic input model with action enum and validation for get/update/refresh operations, inheriting budget_id from BudgetIdInput.

  class ManageFinancialOverviewAction(str, Enum):
      GET = "get"
      UPDATE = "update"
      REFRESH = "refresh"
  
  
  class ManageFinancialOverviewInput(BudgetIdInput):
      action: ManageFinancialOverviewAction = Field(..., description="The action to perform.")
      section: Optional[str] = Field(None, description="The section to update (e.g., 'goals', 'action_items'). Required for 'update' action.")
      data: Optional[dict] = Field(None, description="The new data for the section. Required for 'update' action.")
  
      @model_validator(mode='before')
      @classmethod
      def check_fields_for_action(cls, values):
          action = values.get('action')
          if not action:
              raise ValueError("'action' is a required field.")
  
          if action == 'update':
              if not values.get('section') or not values.get('data'):
                  raise ValueError("'section' and 'data' are required for the 'update' action.")
          
          return values

• src/ynab_mcp_server/server.py:105-109 (registration)

  Tool registration in the MCP server's list_tools() response, including name, description, and input schema reference.

  types.Tool(
      name="manage-financial-overview",
      description="Get, update, or refresh a high-level financial overview. This is the best starting point for any analysis, providing account balances, goals, and important context notes.",
      inputSchema=ManageFinancialOverviewInput.model_json_schema(),
  ),