search_demographics

Retrieve demographic targeting options for Meta Ads campaigns to define audience segments based on age, location, interests, and other criteria.

Instructions

Get demographic targeting options.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    demographic_class: Type of demographics to retrieve. Options: 'demographics', 'life_events', 
                      'industries', 'income', 'family_statuses', 'user_device', 'user_os' (default: 'demographics')
    limit: Maximum number of results to return (default: 50)

Returns:
    JSON string containing demographic targeting options with id, name, audience_size bounds, path, and description

Input Schema

TableJSON Schema

Name	Required	Default
`access_token`	No
`demographic_class`	No	demographics
`limit`	No

Implementation Reference

meta_ads_mcp/core/targeting.py:479-503 (handler)

The primary handler function for the 'search_demographics' MCP tool. Decorated with @mcp_server.tool() for registration and @meta_api_tool for API integration. Searches Meta Ads API for demographic targeting categories like demographics, life events, etc., returning JSON results.

@mcp_server.tool()
@meta_api_tool
async def search_demographics(access_token: Optional[str] = None, demographic_class: str = "demographics", limit: int = 50) -> str:
    """
    Get demographic targeting options.
    
    Args:
        access_token: Meta API access token (optional - will use cached token if not provided)
        demographic_class: Type of demographics to retrieve. Options: 'demographics', 'life_events', 
                          'industries', 'income', 'family_statuses', 'user_device', 'user_os' (default: 'demographics')
        limit: Maximum number of results to return (default: 50)
    
    Returns:
        JSON string containing demographic targeting options with id, name, audience_size bounds, path, and description
    """
    endpoint = "search"
    params = {
        "type": "adTargetingCategory",
        "class": demographic_class,
        "limit": limit
    }
    
    data = await make_api_request(endpoint, access_token, params)
    
    return json.dumps(data, indent=2)

meta_ads_mcp/core/__init__.py:14-14 (registration)
Package-level import of search_demographics from the targeting module. Importing the decorated function registers it as an MCP tool in the core package namespace.
```
from .targeting import search_interests, get_interest_suggestions, estimate_audience_size, search_behaviors, search_demographics, search_geo_locations
```

meta_ads_mcp/__init__.py:38-60 (registration)

Re-export of search_demographics from core subpackage to top-level package namespace, making the registered tool available at the package root.

from .core import (
    get_ad_accounts,
    get_account_info,
    get_campaigns,
    get_campaign_details,
    create_campaign,
    get_adsets,
    get_adset_details,
    update_adset,
    get_ads,
    get_ad_details,
    get_ad_creatives,
    get_ad_image,
    update_ad,
    get_insights,
    login_cli,
    main,
    search_interests,
    get_interest_suggestions,
    estimate_audience_size,
    search_behaviors,
    search_demographics,
    search_geo_locations

Meta Ads MCP