ArmaVita Meta Ads MCP

Instructions

Implementation Reference

• src/armavita_meta_ads_mcp/core/campaign_tools.py:132-208 (handler)

  The 'create_campaign' function, decorated with @mcp_server.tool(), is the primary handler that executes the campaign creation logic via the Meta Graph API.

  async def create_campaign(
      ad_account_id: str,
      name: str,
      objective: str,
      meta_access_token: Optional[str] = None,
      status: str = "PAUSED",
      special_ad_categories: Optional[List[str]] = None,
      daily_budget: Optional[int] = None,
      lifetime_budget: Optional[int] = None,
      buying_type: Optional[str] = None,
      bid_strategy: Optional[str] = None,
      bid_cap: Optional[int] = None,
      spend_cap: Optional[int] = None,
      campaign_budget_optimization: Optional[bool] = None,
      ab_test_control_setups: Optional[List[Dict[str, Any]]] = None,
      use_ad_set_level_budgets: bool = False,
  ) -> str:
      """Create a campaign with optional budgeting and bid controls."""
      if not ad_account_id:
          return _json({"error": "No account ID provided"})
      if not name:
          return _json({"error": "No campaign name provided"})
      if not objective:
          return _json({"error": "No campaign objective provided"})
  
      categories, category_error = _normalize_special_ad_categories(special_ad_categories)
      if category_error:
          return _json({"error": category_error})
  
      bid_error = _validate_bid_strategy(bid_strategy)
      if bid_error:
          return _json(bid_error)
  
      auto_budget_applied = False
      if not use_ad_set_level_budgets and daily_budget is None and lifetime_budget is None:
          daily_budget = 1000
          auto_budget_applied = True
  
      payload: Dict[str, Any] = {
          "name": name,
          "objective": objective,
          "status": status,
          "special_ad_categories": json.dumps(categories),
      }
  
      if use_ad_set_level_budgets:
          payload["is_adset_budget_sharing_enabled"] = "false"
      else:
          if daily_budget is not None:
              payload["daily_budget"] = str(daily_budget)
          if lifetime_budget is not None:
              payload["lifetime_budget"] = str(lifetime_budget)
          if campaign_budget_optimization is not None:
              payload["campaign_budget_optimization"] = "true" if campaign_budget_optimization else "false"
  
      if buying_type is not None:
          payload["buying_type"] = buying_type
      if bid_strategy is not None:
          payload["bid_strategy"] = str(bid_strategy).strip().upper()
      if bid_cap is not None:
          payload["bid_cap"] = str(bid_cap)
      if spend_cap is not None:
          payload["spend_cap"] = str(spend_cap)
      if ab_test_control_setups:
          payload["ab_test_control_setups"] = ab_test_control_setups
  
      result = await make_api_request(f"{ad_account_id}/campaigns", meta_access_token, payload, method="POST")
  
      if isinstance(result, dict):
          if use_ad_set_level_budgets:
              result["budget_strategy"] = "ad_set_level"
              result["note"] = "Campaign created with ad set level budgets. Set budgets on child ad sets."
          elif auto_budget_applied:
              result["budget_default_applied"] = "daily_budget=1000"
              result["note"] = "No campaign budget provided, so MCP applied daily_budget=1000."
  
      return _json(result)