Meta Ads MCP

Instructions

Get pages associated with a Meta Ads account.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)

Returns:
    JSON response with pages associated with the account

Implementation Reference

• meta_ads_mcp/core/ads.py:1305-1514 (handler)

  Primary handler function for the 'get_account_pages' MCP tool. Implements comprehensive multi-approach discovery of Facebook pages associated with a Meta Ads account using various Graph API endpoints (me/accounts, owned_pages, client_pages, ad creatives, ads tracking_specs, etc.). Registered via @mcp_server.tool() decorator. Handles 'me' special case and normalizes account IDs.

  @mcp_server.tool()
  @meta_api_tool
  async def get_account_pages(account_id: str, access_token: Optional[str] = None) -> str:
      """
      Get pages associated with a Meta Ads account.
      
      Args:
          account_id: Meta Ads account ID (format: act_XXXXXXXXX)
          access_token: Meta API access token (optional - will use cached token if not provided)
      
      Returns:
          JSON response with pages associated with the account
      """
      # Check required parameters
      if not account_id:
          return json.dumps({"error": "No account ID provided"}, indent=2)
      
      # Handle special case for 'me'
      if account_id == "me":
          try:
              endpoint = "me/accounts"
              params = {
                  "fields": "id,name,username,category,fan_count,link,verification_status,picture"
              }
              
              user_pages_data = await make_api_request(endpoint, access_token, params)
              return json.dumps(user_pages_data, indent=2)
          except Exception as e:
              return json.dumps({
                  "error": "Failed to get user pages",
                  "details": str(e)
              }, indent=2)
      
      # Ensure account_id has the 'act_' prefix for regular accounts
      if not account_id.startswith("act_"):
          account_id = f"act_{account_id}"
      
      try:
          # Collect all page IDs from multiple approaches
          all_page_ids = set()
          
          # Approach 1: Get user's personal pages (broad scope)
          try:
              endpoint = "me/accounts"
              params = {
                  "fields": "id,name,username,category,fan_count,link,verification_status,picture"
              }
              user_pages_data = await make_api_request(endpoint, access_token, params)
              if "data" in user_pages_data:
                  for page in user_pages_data["data"]:
                      if "id" in page:
                          all_page_ids.add(page["id"])
          except Exception:
              pass
          
          # Approach 2: Try business manager pages
          try:
              # Strip 'act_' prefix to get raw account ID for business endpoints
              raw_account_id = account_id.replace("act_", "")
              endpoint = f"{raw_account_id}/owned_pages"
              params = {
                  "fields": "id,name,username,category,fan_count,link,verification_status,picture"
              }
              business_pages_data = await make_api_request(endpoint, access_token, params)
              if "data" in business_pages_data:
                  for page in business_pages_data["data"]:
                      if "id" in page:
                          all_page_ids.add(page["id"])
          except Exception:
              pass
          
          # Approach 3: Try ad account client pages
          try:
              endpoint = f"{account_id}/client_pages"
              params = {
                  "fields": "id,name,username,category,fan_count,link,verification_status,picture"
              }
              client_pages_data = await make_api_request(endpoint, access_token, params)
              if "data" in client_pages_data:
                  for page in client_pages_data["data"]:
                      if "id" in page:
                          all_page_ids.add(page["id"])
          except Exception:
              pass
          
          # Approach 4: Extract page IDs from all ad creatives (broader creative search)
          try:
              endpoint = f"{account_id}/adcreatives"
              params = {
                  "fields": "id,name,object_story_spec,link_url,call_to_action,image_hash",
                  "limit": 100
              }
              creatives_data = await make_api_request(endpoint, access_token, params)
              if "data" in creatives_data:
                  for creative in creatives_data["data"]:
                      if "object_story_spec" in creative and "page_id" in creative["object_story_spec"]:
                          all_page_ids.add(creative["object_story_spec"]["page_id"])
          except Exception:
              pass
              
          # Approach 5: Get active ads and extract page IDs from creatives
          try:
              endpoint = f"{account_id}/ads"
              params = {
                  "fields": "creative{object_story_spec{page_id},link_url,call_to_action}",
                  "limit": 100
              }
              ads_data = await make_api_request(endpoint, access_token, params)
              if "data" in ads_data:
                  for ad in ads_data.get("data", []):
                      if "creative" in ad and "object_story_spec" in ad["creative"] and "page_id" in ad["creative"]["object_story_spec"]:
                          all_page_ids.add(ad["creative"]["object_story_spec"]["page_id"])
          except Exception:
              pass
  
          # Approach 6: Try promoted_objects endpoint
          try:
              endpoint = f"{account_id}/promoted_objects"
              params = {
                  "fields": "page_id,object_store_url,product_set_id,application_id"
              }
              promoted_objects_data = await make_api_request(endpoint, access_token, params)
              if "data" in promoted_objects_data:
                  for obj in promoted_objects_data["data"]:
                      if "page_id" in obj:
                          all_page_ids.add(obj["page_id"])
          except Exception:
              pass
  
          # Approach 7: Extract page IDs from tracking_specs in ads (most reliable)
          try:
              endpoint = f"{account_id}/ads"
              params = {
                  "fields": "id,name,status,creative,tracking_specs",
                  "limit": 100
              }
              tracking_ads_data = await make_api_request(endpoint, access_token, params)
              if "data" in tracking_ads_data:
                  for ad in tracking_ads_data.get("data", []):
                      tracking_specs = ad.get("tracking_specs", [])
                      if isinstance(tracking_specs, list):
                          for spec in tracking_specs:
                              if isinstance(spec, dict) and "page" in spec:
                                  page_list = spec["page"]
                                  if isinstance(page_list, list):
                                      for page_id in page_list:
                                          if isinstance(page_id, (str, int)) and str(page_id).isdigit():
                                              all_page_ids.add(str(page_id))
          except Exception:
              pass
              
          # Approach 8: Try campaigns and extract page info
          try:
              endpoint = f"{account_id}/campaigns"
              params = {
                  "fields": "id,name,promoted_object,objective",
                  "limit": 50
              }
              campaigns_data = await make_api_request(endpoint, access_token, params)
              if "data" in campaigns_data:
                  for campaign in campaigns_data["data"]:
                      if "promoted_object" in campaign and "page_id" in campaign["promoted_object"]:
                          all_page_ids.add(campaign["promoted_object"]["page_id"])
          except Exception:
              pass
              
          # If we found any page IDs, get details for each
          if all_page_ids:
              page_details = {
                  "data": [], 
                  "total_pages_found": len(all_page_ids)
              }
              
              for page_id in all_page_ids:
                  try:
                      page_endpoint = f"{page_id}"
                      page_params = {
                          "fields": "id,name,username,category,fan_count,link,verification_status,picture"
                      }
                      
                      page_data = await make_api_request(page_endpoint, access_token, page_params)
                      if "id" in page_data:
                          page_details["data"].append(page_data)
                      else:
                          page_details["data"].append({
                              "id": page_id, 
                              "error": "Page details not accessible"
                          })
                  except Exception as e:
                      page_details["data"].append({
                          "id": page_id,
                          "error": f"Failed to get page details: {str(e)}"
                      })
              
              if page_details["data"]:
                  return json.dumps(page_details, indent=2)
          
          # If all approaches failed, return empty data with a message
          return json.dumps({
              "data": [],
              "message": "No pages found associated with this account",
              "suggestion": "Create a Facebook page and connect it to this ad account, or ensure existing pages are properly connected through Business Manager"
          }, indent=2)
          
      except Exception as e:
          return json.dumps({
              "error": "Failed to get account pages",
              "details": str(e)
          }, indent=2)