Meta Ads MCP

Instructions

Get ads for a Meta Ads account with optional filtering.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)
    limit: Maximum number of ads to return (default: 10)
    campaign_id: Optional campaign ID to filter by
    adset_id: Optional ad set ID to filter by

Implementation Reference

• meta_ads_mcp/core/ads.py:21-64 (handler)

  The get_ads tool handler: Retrieves ads from a specified Meta Ads account ID, with optional filtering by adset_id or campaign_id, using the Meta Ads API. Returns JSON-formatted list of ads.

  @mcp_server.tool()
  @meta_api_tool
  async def get_ads(account_id: str, access_token: Optional[str] = None, limit: int = 10, 
                   campaign_id: str = "", adset_id: str = "") -> str:
      """
      Get ads for a Meta Ads account with optional filtering.
      
      Args:
          account_id: Meta Ads account ID (format: act_XXXXXXXXX)
          access_token: Meta API access token (optional - will use cached token if not provided)
          limit: Maximum number of ads to return (default: 10)
          campaign_id: Optional campaign ID to filter by
          adset_id: Optional ad set ID to filter by
      """
      # Require explicit account_id
      if not account_id:
          return json.dumps({"error": "No account ID specified"}, indent=2)
      
      # Prioritize adset_id over campaign_id - use adset-specific endpoint
      if adset_id:
          endpoint = f"{adset_id}/ads"
          params = {
              "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
              "limit": limit
          }
      # Use campaign-specific endpoint if campaign_id is provided
      elif campaign_id:
          endpoint = f"{campaign_id}/ads"
          params = {
              "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
              "limit": limit
          }
      else:
          # Default to account-level endpoint if no specific filters
          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": limit
          }
  
      data = await make_api_request(endpoint, access_token, params)
      
      return json.dumps(data, indent=2)

• meta_ads_mcp/core/__init__.py:7-8 (registration)

  Imports and re-exports the get_ads function from ads.py module, making it available at the core package level for MCP tool registration.

  from .ads import get_ads, get_ad_details, get_ad_creatives, get_ad_image, update_ad
  from .insights import get_insights

• meta_ads_mcp/__init__.py:47-47 (registration)

  Re-exports get_ads from core package in the main package __init__.py, including it in __all__ for top-level package access.

  get_ads,