get_ads
Retrieve and filter Meta Ads for a specific account using an access token, account ID, and optional campaign or ad set filters. Defaults to returning 10 ads.
Instructions
Get ads for a Meta Ads account with optional filtering.
Args:
access_token: Meta API access token (optional - will use cached token if not provided)
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
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
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| access_token | No | ||
| account_id | No | ||
| adset_id | No | ||
| campaign_id | No | ||
| limit | No |
Implementation Reference
- meta_ads_mcp/core/ads.py:21-64 (handler)The core handler function for the 'get_ads' MCP tool. It fetches ads from the Meta Ads API using the provided account_id, optionally filtered by campaign_id or adset_id. Decorated with @mcp_server.tool() for MCP registration and @meta_api_tool for API handling.@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/__init__.py:47-47 (registration)Package-level export of the get_ads function from core, making it available when importing from meta_ads_mcpget_ads,
- meta_ads_mcp/core/__init__.py:29-29 (registration)Core module export of get_ads in __all__, and import from .ads on line 7.'get_ads',
- meta_ads_mcp/core/ads.py:25-34 (schema)Input schema and documentation for the get_ads tool parameters.""" 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 """