Meta Ads MCP

Instructions

Implementation Reference

• meta_ads_mcp/core/ads.py:1286-1494 (handler)

  Primary handler for the 'get_account_pages' MCP tool. Uses comprehensive multi-approach discovery across Graph API endpoints (me/accounts, owned_pages, client_pages, creatives, ads tracking_specs, etc.) to find all Facebook Pages usable with the ad account. Includes special handling for 'me' keyword and robust error recovery. Registered via @mcp_server.tool() decorator.
  @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)
• meta_ads_mcp/core/ads.py:1286-1286 (registration)

  The @mcp_server.tool() decorator registers the get_account_pages function as an MCP tool with the name 'get_account_pages'. The @meta_api_tool decorator adds Meta API handling.
  @meta_api_tool