google_ads_create_performance_max_campaign

Instructions

Implementation Reference

• tools/shopping_pmax/mcp_tools_shopping_pmax.py:367-463 (handler)

  The MCP tool handler function 'google_ads_create_performance_max_campaign' decorated with @mcp.tool(). It accepts customer_id, campaign_name, budget_amount, conversion_goals_json, target_roas, target_cpa. It parses conversion goals JSON, creates a PerformanceMaxCampaignConfig, and delegates to ShoppingPMaxManager.create_performance_max_campaign(). Returns a formatted result string.

  @mcp.tool()
  def google_ads_create_performance_max_campaign(
      customer_id: str,
      campaign_name: str,
      budget_amount: float,
      conversion_goals_json: str,
      target_roas: Optional[float] = None,
      target_cpa: Optional[float] = None
  ) -> str:
      """Create a Performance Max campaign.
  
      Performance Max uses Google's AI to optimize across all Google channels:
      Search, Display, YouTube, Gmail, Discover, and Maps.
  
      Args:
          customer_id: Google Ads customer ID (10 digits, no hyphens)
          campaign_name: Name for the Performance Max campaign
          budget_amount: Daily budget in currency units
          conversion_goals_json: JSON array of conversion action names
          target_roas: Optional target return on ad spend (e.g., 3.0 for 300%)
          target_cpa: Optional target cost per acquisition (if not using ROAS)
  
      Example:
          google_ads_create_performance_max_campaign(
              customer_id="1234567890",
              campaign_name="PMax - All Products",
              budget_amount=150.00,
              conversion_goals_json='["Purchase", "Add to Cart"]',
              target_roas=4.0
          )
      """
      with performance_logger.track_operation('create_performance_max', customer_id=customer_id):
          try:
              client = get_auth_manager().get_client()
              shopping_manager = ShoppingPMaxManager(client)
  
              # Parse conversion goals
              try:
                  conversion_goals = json.loads(conversion_goals_json)
              except json.JSONDecodeError:
                  return "❌ Invalid JSON format for conversion_goals_json"
  
              config = PerformanceMaxCampaignConfig(
                  name=campaign_name,
                  budget_amount=budget_amount,
                  conversion_goals=conversion_goals,
                  target_roas=target_roas,
                  target_cpa=target_cpa
              )
  
              result = shopping_manager.create_performance_max_campaign(customer_id, config)
  
              audit_logger.log_api_call(
                  customer_id=customer_id,
                  operation='create_performance_max_campaign',
                  campaign_id=result['campaign_id'],
                  status='success'
              )
  
              output = f"# 🚀 Performance Max Campaign Created\n\n"
              output += f"**Campaign Name**: {result['campaign_name']}\n"
              output += f"**Campaign ID**: {result['campaign_id']}\n"
              output += f"**Daily Budget**: ${result['budget']:.2f}\n"
              output += f"**Bidding Strategy**: {result['bidding_strategy']}\n"
              output += f"**Status**: PAUSED\n\n"
  
              if target_roas:
                  output += f"🎯 **Target ROAS**: {target_roas:.1f}x\n\n"
              elif target_cpa:
                  output += f"🎯 **Target CPA**: ${target_cpa:.2f}\n\n"
  
              output += "## What is Performance Max?\n\n"
              output += "Performance Max uses Google's AI to show your ads across:\n"
              output += "- 🔍 Google Search\n"
              output += "- 📺 YouTube\n"
              output += "- 📧 Gmail\n"
              output += "- 🌐 Display Network\n"
              output += "- 📱 Discover\n"
              output += "- 🗺️ Google Maps\n\n"
  
              output += "## Next Steps\n\n"
              output += "1. ✅ Campaign created successfully\n"
              output += "2. 📦 Create asset groups with:\n"
              output += "   - Headlines (3-15)\n"
              output += "   - Descriptions (2-5)\n"
              output += "   - Images (at least 1)\n"
              output += "   - Videos (optional)\n"
              output += "3. 🎯 Add audience signals to guide AI\n"
              output += "4. ▶️ Enable campaign when assets are ready\n\n"
  
              output += "💡 **Tip**: Performance Max needs 6-8 weeks of learning to optimize fully.\n"
  
              return output
  
          except Exception as e:
              error_msg = ErrorHandler.handle_error(e, context="create_performance_max")
              return f"❌ Failed to create Performance Max campaign: {error_msg}"

• managers/shopping_pmax_manager.py:54-61 (schema)

  The PerformanceMaxCampaignConfig dataclass defining the schema for PMax campaign creation — fields: name, budget_amount, conversion_goals, target_roas, target_cpa.

  class PerformanceMaxCampaignConfig:
      """Configuration for Performance Max campaign creation."""
      name: str
      budget_amount: float
      conversion_goals: List[str]
      target_roas: Optional[float] = None
      target_cpa: Optional[float] = None

• managers/shopping_pmax_manager.py:315-376 (helper)

  The backend manager method 'create_performance_max_campaign' that performs the actual Google Ads API calls — creates a campaign budget, sets up a PERFORMANCE_MAX campaign with PAUSED status, configures bidding (TARGET_ROAS or MAXIMIZE_CONVERSIONS), and returns campaign details.

  def create_performance_max_campaign(
      self,
      customer_id: str,
      config: PerformanceMaxCampaignConfig
  ) -> Dict[str, Any]:
      """Create a Performance Max campaign.
  
      Args:
          customer_id: Customer ID (without hyphens)
          config: Performance Max campaign configuration
  
      Returns:
          Created campaign details
      """
      campaign_service = self.client.get_service("CampaignService")
      campaign_budget_service = self.client.get_service("CampaignBudgetService")
  
      # Create campaign budget
      budget_operation = self.client.get_type("CampaignBudgetOperation")
      budget = budget_operation.create
      budget.name = f"{config.name} Budget"
      budget.amount_micros = int(config.budget_amount * 1_000_000)
      budget.delivery_method = self.client.enums.BudgetDeliveryMethodEnum.STANDARD
  
      budget_response = campaign_budget_service.mutate_campaign_budgets(
          customer_id=customer_id,
          operations=[budget_operation]
      )
      budget_resource_name = budget_response.results[0].resource_name
  
      # Create Performance Max campaign
      campaign_operation = self.client.get_type("CampaignOperation")
      campaign = campaign_operation.create
  
      campaign.name = config.name
      campaign.advertising_channel_type = self.client.enums.AdvertisingChannelTypeEnum.PERFORMANCE_MAX
      campaign.status = self.client.enums.CampaignStatusEnum.PAUSED
      campaign.campaign_budget = budget_resource_name
  
      # Bidding strategy
      if config.target_roas:
          campaign.maximize_conversion_value.target_roas = config.target_roas
      elif config.target_cpa:
          campaign.maximize_conversions.target_cpa_micros = int(config.target_cpa * 1_000_000)
      else:
          campaign.maximize_conversions.target_cpa_micros = 0
  
      # Create campaign
      response = campaign_service.mutate_campaigns(
          customer_id=customer_id,
          operations=[campaign_operation]
      )
  
      campaign_id = response.results[0].resource_name.split('/')[-1]
  
      return {
          'campaign_id': campaign_id,
          'campaign_name': config.name,
          'resource_name': response.results[0].resource_name,
          'budget': config.budget_amount,
          'bidding_strategy': 'TARGET_ROAS' if config.target_roas else 'MAXIMIZE_CONVERSIONS'
      }

• google_ads_mcp.py:492-492 (registration)

  Registration entry in _TOOL_MODULES list that maps 'shopping_pmax' to the module 'tools.shopping_pmax.mcp_tools_shopping_pmax' and function 'register_shopping_pmax_tools'.

  ("shopping_pmax", "tools.shopping_pmax.mcp_tools_shopping_pmax", "register_shopping_pmax_tools"),

• tools/shopping_pmax/mcp_tools_shopping_pmax.py:37-38 (registration)

  The 'register_shopping_pmax_tools' function definition that receives the MCP instance and registers the tool via the @mcp.tool() decorator.

  def register_shopping_pmax_tools(mcp):
      """Register all Shopping and Performance Max MCP tools."""