meta-ads-mcp 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

meta_ads_mcp/__init__.py

@@ -7,7 +7,7 @@ with the Claude LLM.
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     'get_ad_accounts',
@@ -26,7 +26,13 @@ __all__ = [
     'get_insights',
     'get_login_link',
     'login_cli',
-    'main'
+    'main',
+    'search_interests',
+    'get_interest_suggestions',
+    'validate_interests',
+    'search_behaviors',
+    'search_demographics',
+    'search_geo_locations'
 ]
 
 # Import key functions to make them available at package level
@@ -47,7 +53,13 @@ from .core import (
     get_insights,
     get_login_link,
     login_cli,
-    main
+    main,
+    search_interests,
+    get_interest_suggestions,
+    validate_interests,
+    search_behaviors,
+    search_demographics,
+    search_geo_locations
 )
 
 # Define a main function to be used as a package entry point

meta_ads_mcp/core/__init__.py

@@ -11,6 +11,7 @@ from .server import login_cli, main
 from .auth import login
 from .ads_library import search_ads_archive
 from .budget_schedules import create_budget_schedule
+from .targeting import search_interests, get_interest_suggestions, validate_interests, search_behaviors, search_demographics, search_geo_locations
 from . import reports  # Import module to register conditional tools
 from . import duplication  # Import module to register conditional duplication tools
 from .openai_deep_research import search, fetch  # OpenAI MCP Deep Research tools
@@ -37,6 +38,12 @@ __all__ = [
     'main',
     'search_ads_archive',
     'create_budget_schedule',
+    'search_interests',
+    'get_interest_suggestions',
+    'validate_interests',
+    'search_behaviors',
+    'search_demographics',
+    'search_geo_locations',
     'search',  # OpenAI MCP Deep Research search tool
     'fetch',   # OpenAI MCP Deep Research fetch tool
 ] 

meta_ads_mcp/core/targeting.py

@@ -0,0 +1,185 @@
+"""Targeting search functionality for Meta Ads API."""
+
+import json
+from typing import Optional, List, Dict, Any
+from .api import meta_api_tool, make_api_request
+from .server import mcp_server
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_interests(access_token: str = None, query: str = None, limit: int = 25) -> str:
+    """
+    Search for interest targeting options by keyword.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        query: Search term for interests (e.g., "baseball", "cooking", "travel")
+        limit: Maximum number of results to return (default: 25)
+    
+    Returns:
+        JSON string containing interest data with id, name, audience_size, and path fields
+    """
+    if not query:
+        return json.dumps({"error": "No search query provided"}, indent=2)
+    
+    endpoint = "search"
+    params = {
+        "type": "adinterest",
+        "q": query,
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_interest_suggestions(access_token: str = None, interest_list: List[str] = None, limit: int = 25) -> str:
+    """
+    Get interest suggestions based on existing interests.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)  
+        interest_list: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])
+        limit: Maximum number of suggestions to return (default: 25)
+    
+    Returns:
+        JSON string containing suggested interests with id, name, audience_size, and description fields
+    """
+    if not interest_list:
+        return json.dumps({"error": "No interest list provided"}, indent=2)
+    
+    endpoint = "search"
+    params = {
+        "type": "adinterestsuggestion", 
+        "interest_list": json.dumps(interest_list),
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def validate_interests(access_token: str = None, interest_list: List[str] = None, 
+                           interest_fbid_list: List[str] = None) -> str:
+    """
+    Validate interest names or IDs for targeting.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        interest_list: List of interest names to validate (e.g., ["Japan", "Basketball"])
+        interest_fbid_list: List of interest IDs to validate (e.g., ["6003700426513"])
+    
+    Returns:
+        JSON string with validation results showing valid status and audience_size for each interest
+    """
+    if not interest_list and not interest_fbid_list:
+        return json.dumps({"error": "No interest list or FBID list provided"}, indent=2)
+    
+    endpoint = "search"
+    params = {
+        "type": "adinterestvalid"
+    }
+    
+    if interest_list:
+        params["interest_list"] = json.dumps(interest_list)
+    
+    if interest_fbid_list:
+        params["interest_fbid_list"] = json.dumps(interest_fbid_list)
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_behaviors(access_token: str = None, limit: int = 50) -> str:
+    """
+    Get all available behavior targeting options.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        limit: Maximum number of results to return (default: 50)
+    
+    Returns:
+        JSON string containing behavior targeting options with id, name, audience_size bounds, path, and description
+    """
+    endpoint = "search"
+    params = {
+        "type": "adTargetingCategory",
+        "class": "behaviors",
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_demographics(access_token: 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)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_geo_locations(access_token: str = None, query: str = None, 
+                             location_types: List[str] = None, limit: int = 25) -> str:
+    """
+    Search for geographic targeting locations.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        query: Search term for locations (e.g., "New York", "California", "Japan")
+        location_types: Types of locations to search. Options: ['country', 'region', 'city', 'zip', 
+                       'geo_market', 'electoral_district']. If not specified, searches all types.
+        limit: Maximum number of results to return (default: 25)
+    
+    Returns:
+        JSON string containing location data with key, name, type, and geographic hierarchy information
+    """
+    if not query:
+        return json.dumps({"error": "No search query provided"}, indent=2)
+    
+    endpoint = "search"
+    params = {
+        "type": "adgeolocation",
+        "q": query,
+        "limit": limit
+    }
+    
+    if location_types:
+        params["location_types"] = json.dumps(location_types)
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2) 

{meta_ads_mcp-0.6.0.dist-info → meta_ads_mcp-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.6.0
+Version: 0.7.0
 Summary: Model Context Protocol (MCP) plugin for interacting with Meta Ads API
 Project-URL: Homepage, https://github.com/pipeboard-co/meta-ads-mcp
 Project-URL: Bug Tracker, https://github.com/pipeboard-co/meta-ads-mcp/issues
@@ -331,6 +331,54 @@ For local installation configuration, authentication options, and advanced techn
       - `access_token` (optional): Meta API access token.
     - Returns: JSON string with the ID of the created budget schedule or an error message.
 
+22. `mcp_meta_ads_search_interests`
+    - Search for interest targeting options by keyword
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `query`: Search term for interests (e.g., "baseball", "cooking", "travel")
+      - `limit`: Maximum number of results to return (default: 25)
+    - Returns: Interest data with id, name, audience_size, and path fields
+
+23. `mcp_meta_ads_get_interest_suggestions`
+    - Get interest suggestions based on existing interests
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `interest_list`: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])
+      - `limit`: Maximum number of suggestions to return (default: 25)
+    - Returns: Suggested interests with id, name, audience_size, and description fields
+
+24. `mcp_meta_ads_validate_interests`
+    - Validate interest names or IDs for targeting
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `interest_list`: List of interest names to validate (e.g., ["Japan", "Basketball"])
+      - `interest_fbid_list`: List of interest IDs to validate (e.g., ["6003700426513"])
+    - Returns: Validation results showing valid status and audience_size for each interest
+
+25. `mcp_meta_ads_search_behaviors`
+    - Get all available behavior targeting options
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `limit`: Maximum number of results to return (default: 50)
+    - Returns: Behavior targeting options with id, name, audience_size bounds, path, and description
+
+26. `mcp_meta_ads_search_demographics`
+    - Get demographic targeting options
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `demographic_class`: Type of demographics ('demographics', 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os')
+      - `limit`: Maximum number of results to return (default: 50)
+    - Returns: Demographic targeting options with id, name, audience_size bounds, path, and description
+
+27. `mcp_meta_ads_search_geo_locations`
+    - Search for geographic targeting locations
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `query`: Search term for locations (e.g., "New York", "California", "Japan")
+      - `location_types`: Types of locations to search (['country', 'region', 'city', 'zip', 'geo_market', 'electoral_district'])
+      - `limit`: Maximum number of results to return (default: 25)
+    - Returns: Location data with key, name, type, and geographic hierarchy information
+
 ## Privacy and Security
 
 Meta Ads MCP follows security best practices with secure token management and automatic authentication handling. 

{meta_ads_mcp-0.6.0.dist-info → meta_ads_mcp-0.7.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
-meta_ads_mcp/__init__.py,sha256=PTxucSykpztlUP9BWOaKYzAgz2lv4N6MIn30ZOVeZvY,1182
+meta_ads_mcp/__init__.py,sha256=UDuLAO7mGVeZrzSJhTr3UAJKug3oHb6IK6OjooX6fk8,1492
 meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
-meta_ads_mcp/core/__init__.py,sha256=FgChGSexAsJhrL9RC6CSSxzYvggOttEIfl9ZhjAO3nA,1398
+meta_ads_mcp/core/__init__.py,sha256=IHBUfLTQW44VLbH_gZDT83nqzGrVWZ0l7FG4P3bp_bU,1706
 meta_ads_mcp/core/accounts.py,sha256=Nmp7lPxO9wmq25jWV7_H0LIqnEbBhpCVBlLGW2HUaq0,2277
 meta_ads_mcp/core/ads.py,sha256=aaK70mgfhBJRXr4cdkKag5mjYzvHuHpRttJvTMzPk4Y,36156
 meta_ads_mcp/core/ads_library.py,sha256=onStn9UkRqYDC60gOPS-iKDtP1plz6DygUb7hUZ0Jw8,2807
@@ -19,9 +19,10 @@ meta_ads_mcp/core/pipeboard_auth.py,sha256=VvbxEB8ZOhnMccLU7HI1HgaPWHCl5NGrzZCm-
 meta_ads_mcp/core/reports.py,sha256=Dv3hfsPOR7IZ9WrYrKd_6SNgZl-USIphg7knva3UYAw,5747
 meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
 meta_ads_mcp/core/server.py,sha256=WhbAag7xdhbGcp7rnU4sKhqXJ8Slapa_ba3T23Yp_2U,17889
+meta_ads_mcp/core/targeting.py,sha256=3HW1qirEdwaQurlBZGenbIwawcb5J06ghJKRfgu9ZEs,6318
 meta_ads_mcp/core/utils.py,sha256=ofKUhyo-5SZoJVuBeTVFPPQCffk0UKpwmDMrd8qQxNc,8715
-meta_ads_mcp-0.6.0.dist-info/METADATA,sha256=R00OLW0uiiYb7aSaksy1VR2xKGDD-FFHDgjiS7nO1WA,17580
-meta_ads_mcp-0.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.6.0.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.6.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-meta_ads_mcp-0.6.0.dist-info/RECORD,,
+meta_ads_mcp-0.7.0.dist-info/METADATA,sha256=ADo7W0ulgt6gIZzJjOkyxM-PDqE0inab-THLjsStoGo,20409
+meta_ads_mcp-0.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.7.0.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.7.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+meta_ads_mcp-0.7.0.dist-info/RECORD,,