Meta Ads MCP

Instructions

Implementation Reference

• meta_ads_mcp/core/ads.py:1282-1302 (handler)

  Main handler function for the MCP tool 'search_pages_by_name', registered via @mcp_server.tool() decorator. Delegates to internal _search_pages_by_name_core.
  @mcp_server.tool() @meta_api_tool async def search_pages_by_name(account_id: str, access_token: Optional[str] = None, search_term: Optional[str] = None) -> str: """ Search for pages by name within an 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) search_term: Search term to find pages by name (optional - returns all pages if not provided) Returns: JSON response with matching pages """ # Check required parameters if not account_id: return json.dumps({"error": "No account ID provided"}, indent=2) # Call the core function result = await _search_pages_by_name_core(access_token, account_id, search_term) return result
• meta_ads_mcp/core/ads.py:1215-1280 (helper)

  Core helper function implementing the page search logic, including filtering by search_term and using _discover_pages_for_account.
  async def _search_pages_by_name_core(access_token: str, account_id: str, search_term: str = None) -> str: """ Core logic for searching pages by name. Args: access_token: Meta API access token account_id: Meta Ads account ID (format: act_XXXXXXXXX) search_term: Search term to find pages by name (optional - returns all pages if not provided) Returns: JSON string with search results """ # Ensure account_id has the 'act_' prefix if not account_id.startswith("act_"): account_id = f"act_{account_id}" try: # Use the internal discovery function directly page_discovery_result = await _discover_pages_for_account(account_id, access_token) if not page_discovery_result.get("success"): return json.dumps({ "data": [], "message": "No pages found for this account", "details": page_discovery_result.get("message", "Page discovery failed") }, indent=2) # Create a single page result page_data = { "id": page_discovery_result["page_id"], "name": page_discovery_result.get("page_name", "Unknown"), "source": page_discovery_result.get("source", "unknown") } all_pages_data = {"data": [page_data]} # Filter pages by search term if provided if search_term: search_term_lower = search_term.lower() filtered_pages = [] for page in all_pages_data["data"]: page_name = page.get("name", "").lower() if search_term_lower in page_name: filtered_pages.append(page) return json.dumps({ "data": filtered_pages, "search_term": search_term, "total_found": len(filtered_pages), "total_available": len(all_pages_data["data"]) }, indent=2) else: # Return all pages if no search term provided return json.dumps({ "data": all_pages_data["data"], "total_available": len(all_pages_data["data"]), "note": "Use search_term parameter to filter pages by name" }, indent=2) except Exception as e: return json.dumps({ "error": "Failed to search pages by name", "details": str(e) }, indent=2)
• meta_ads_mcp/core/ads.py:1120-1213 (helper)

  Supporting helper that discovers pages for an account using multiple Meta API endpoints, prioritized by reliability.
  async def _discover_pages_for_account(account_id: str, access_token: str) -> dict: """ Internal function to discover pages for an account using multiple approaches. Returns the best available page ID for ad creation. """ try: # Approach 1: Extract page IDs from tracking_specs in ads (most reliable) endpoint = f"{account_id}/ads" params = { "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs", "limit": 100 } tracking_ads_data = await make_api_request(endpoint, access_token, params) tracking_page_ids = set() 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(): tracking_page_ids.add(str(page_id)) if tracking_page_ids: # Get details for the first page found page_id = list(tracking_page_ids)[0] 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: return { "success": True, "page_id": page_id, "page_name": page_data.get("name", "Unknown"), "source": "tracking_specs", "note": "Page ID extracted from existing ads - most reliable for ad creation" } # Approach 2: Try client_pages endpoint 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 and client_pages_data["data"]: page = client_pages_data["data"][0] return { "success": True, "page_id": page["id"], "page_name": page.get("name", "Unknown"), "source": "client_pages" } # Approach 3: Try assigned_pages endpoint pages_endpoint = f"{account_id}/assigned_pages" pages_params = { "fields": "id,name", "limit": 1 } pages_data = await make_api_request(pages_endpoint, access_token, pages_params) if "data" in pages_data and pages_data["data"]: page = pages_data["data"][0] return { "success": True, "page_id": page["id"], "page_name": page.get("name", "Unknown"), "source": "assigned_pages" } # If all approaches failed return { "success": False, "message": "No suitable pages found for this account", "note": "Try using get_account_pages to see all available pages or provide page_id manually" } except Exception as e: return { "success": False, "message": f"Error during page discovery: {str(e)}" }