meta-ads-mcp 0.3.2__py3-none-any.whl → 0.3.5__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.3.2"
+__version__ = "0.3.5"
 
 __all__ = [
     'get_ad_accounts',

meta_ads_mcp/core/__init__.py

@@ -9,6 +9,8 @@ from .insights import get_insights, debug_image_download
 from .authentication import get_login_link
 from .server import login_cli, main
 from .auth import login
+from .ads_library import search_ads_archive
+from .budget_schedules import create_budget_schedule
 
 __all__ = [
     'mcp_server',
@@ -31,4 +33,6 @@ __all__ = [
     'login_cli',
     'login',
     'main',
+    'search_ads_archive',
+    'create_budget_schedule',
 ] 

meta_ads_mcp/core/ads.py

@@ -5,6 +5,8 @@ from typing import Optional, Dict, Any, List
 import io
 from PIL import Image as PILImage
 from mcp.server.fastmcp import Image
+import os
+import time
 
 from .api import meta_api_tool, make_api_request
 from .accounts import get_ad_accounts
@@ -317,6 +319,132 @@ async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
         return f"Error processing image: {str(e)}"
 
 
+@mcp_server.tool()
+@meta_api_tool
+async def save_ad_image_locally(access_token: str = None, ad_id: str = None, output_dir: str = "ad_images") -> str:
+    """
+    Get, download, and save a Meta ad image locally, returning the file path.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+        output_dir: Directory to save the image file (default: 'ad_images')
+    
+    Returns:
+        The file path to the saved image, or an error message string.
+    """
+    if not ad_id:
+        return json.dumps({"error": "No ad ID provided"}, indent=2)
+        
+    print(f"Attempting to get and save creative image for ad {ad_id}")
+    
+    # First, get creative and account IDs
+    ad_endpoint = f"{ad_id}"
+    ad_params = {
+        "fields": "creative{id},account_id"
+    }
+    
+    ad_data = await make_api_request(ad_endpoint, access_token, ad_params)
+    
+    if "error" in ad_data:
+        return json.dumps({"error": f"Could not get ad data - {json.dumps(ad_data)}"}, indent=2)
+    
+    account_id = ad_data.get("account_id")
+    if not account_id:
+        return json.dumps({"error": "No account ID found for ad"}, indent=2)
+    
+    if "creative" not in ad_data:
+        return json.dumps({"error": "No creative found for this ad"}, indent=2)
+        
+    creative_data = ad_data.get("creative", {})
+    creative_id = creative_data.get("id")
+    if not creative_id:
+        return json.dumps({"error": "No creative ID found"}, indent=2)
+    
+    # Get creative details to find image hash
+    creative_endpoint = f"{creative_id}"
+    creative_params = {
+        "fields": "id,name,image_hash,asset_feed_spec"
+    }
+    creative_details = await make_api_request(creative_endpoint, access_token, creative_params)
+    
+    image_hashes = []
+    if "image_hash" in creative_details:
+        image_hashes.append(creative_details["image_hash"])
+    if "asset_feed_spec" in creative_details and "images" in creative_details["asset_feed_spec"]:
+        for image in creative_details["asset_feed_spec"]["images"]:
+            if "hash" in image:
+                image_hashes.append(image["hash"])
+    
+    if not image_hashes:
+        # Fallback attempt (as in get_ad_image)
+        creative_json = await get_ad_creatives(ad_id=ad_id, access_token=access_token) # Ensure ad_id is passed correctly
+        creative_data_list = json.loads(creative_json)
+        if 'data' in creative_data_list and creative_data_list['data']:
+             first_creative = creative_data_list['data'][0]
+             if 'object_story_spec' in first_creative and 'link_data' in first_creative['object_story_spec'] and 'image_hash' in first_creative['object_story_spec']['link_data']:
+                 image_hashes.append(first_creative['object_story_spec']['link_data']['image_hash'])
+             elif 'image_hash' in first_creative: # Check direct hash on creative data
+                  image_hashes.append(first_creative['image_hash'])
+
+
+    if not image_hashes:
+        return json.dumps({"error": "No image hashes found in creative or fallback"}, indent=2)
+
+    print(f"Found image hashes: {image_hashes}")
+    
+    # Fetch image data using the first hash
+    image_endpoint = f"act_{account_id}/adimages"
+    hashes_str = f'["{image_hashes[0]}"]'
+    image_params = {
+        "fields": "hash,url,width,height,name,status",
+        "hashes": hashes_str
+    }
+    
+    print(f"Requesting image data with params: {image_params}")
+    image_data = await make_api_request(image_endpoint, access_token, image_params)
+    
+    if "error" in image_data:
+        return json.dumps({"error": f"Failed to get image data - {json.dumps(image_data)}"}, indent=2)
+    
+    if "data" not in image_data or not image_data["data"]:
+        return json.dumps({"error": "No image data returned from API"}, indent=2)
+        
+    first_image = image_data["data"][0]
+    image_url = first_image.get("url")
+    
+    if not image_url:
+        return json.dumps({"error": "No valid image URL found in API response"}, indent=2)
+        
+    print(f"Downloading image from URL: {image_url}")
+    
+    # Download and Save Image
+    image_bytes = await download_image(image_url)
+    
+    if not image_bytes:
+        return json.dumps({"error": "Failed to download image"}, indent=2)
+        
+    try:
+        # Ensure output directory exists
+        if not os.path.exists(output_dir):
+            os.makedirs(output_dir)
+            
+        # Create a filename (e.g., using ad_id and image hash)
+        file_extension = ".jpg" # Default extension, could try to infer from headers later
+        filename = f"{ad_id}_{image_hashes[0]}{file_extension}"
+        filepath = os.path.join(output_dir, filename)
+        
+        # Save the image bytes to the file
+        with open(filepath, "wb") as f:
+            f.write(image_bytes)
+            
+        print(f"Image saved successfully to: {filepath}")
+        return json.dumps({"filepath": filepath}, indent=2) # Return JSON with filepath
+
+    except Exception as e:
+        return json.dumps({"error": f"Failed to save image: {str(e)}"}, indent=2)
+
+
 @mcp_server.tool()
 @meta_api_tool
 async def update_ad(
@@ -354,4 +482,338 @@ async def update_ad(
     endpoint = f"{ad_id}"
     data = await make_api_request(endpoint, access_token, params, method='POST')
 
-    return json.dumps(data, indent=2)
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def upload_ad_image(
+    access_token: str = None,
+    account_id: str = None,
+    image_path: str = None,
+    name: str = None
+) -> str:
+    """
+    Upload an image to use in Meta Ads creatives.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        image_path: Path to the image file to upload
+        name: Optional name for the image (default: filename)
+    
+    Returns:
+        JSON response with image details including hash for creative creation
+    """
+    # Check required parameters
+    if not account_id:
+        return json.dumps({"error": "No account ID provided"}, indent=2)
+    
+    if not image_path:
+        return json.dumps({"error": "No image path provided"}, indent=2)
+    
+    # Ensure account_id has the 'act_' prefix for API compatibility
+    if not account_id.startswith("act_"):
+        account_id = f"act_{account_id}"
+    
+    # Check if image file exists
+    if not os.path.exists(image_path):
+        return json.dumps({"error": f"Image file not found: {image_path}"}, indent=2)
+    
+    try:
+        # Read image file
+        with open(image_path, "rb") as img_file:
+            image_bytes = img_file.read()
+        
+        # Get image filename if name not provided
+        if not name:
+            name = os.path.basename(image_path)
+        
+        # Prepare the API endpoint for uploading images
+        endpoint = f"{account_id}/adimages"
+        
+        # We need to convert the binary data to base64 for API upload
+        import base64
+        encoded_image = base64.b64encode(image_bytes).decode('utf-8')
+        
+        # Prepare POST parameters
+        params = {
+            "bytes": encoded_image,
+            "name": name
+        }
+        
+        # Make API request to upload the image
+        print(f"Uploading image to Facebook Ad Account {account_id}")
+        data = await make_api_request(endpoint, access_token, params, method="POST")
+        
+        return json.dumps(data, indent=2)
+    
+    except Exception as e:
+        return json.dumps({
+            "error": "Failed to upload image",
+            "details": str(e)
+        }, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def create_ad_creative(
+    access_token: str = None,
+    account_id: str = None,
+    name: str = None,
+    image_hash: str = None,
+    page_id: str = None,
+    link_url: str = None,
+    message: str = None,
+    headline: str = None,
+    description: str = None,
+    call_to_action_type: str = None,
+    instagram_actor_id: str = None
+) -> str:
+    """
+    Create a new ad creative using an uploaded image hash.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        name: Creative name
+        image_hash: Hash of the uploaded image
+        page_id: Facebook Page ID to be used for the ad
+        link_url: Destination URL for the ad
+        message: Ad copy/text
+        headline: Ad headline
+        description: Ad description
+        call_to_action_type: Call to action button type (e.g., 'LEARN_MORE', 'SIGN_UP', 'SHOP_NOW')
+        instagram_actor_id: Optional Instagram account ID for Instagram placements
+    
+    Returns:
+        JSON response with created creative details
+    """
+    # Check required parameters
+    if not account_id:
+        return json.dumps({"error": "No account ID provided"}, indent=2)
+    
+    if not image_hash:
+        return json.dumps({"error": "No image hash provided"}, indent=2)
+    
+    if not name:
+        name = f"Creative {int(time.time())}"
+    
+    # Ensure account_id has the 'act_' prefix
+    if not account_id.startswith("act_"):
+        account_id = f"act_{account_id}"
+    
+    # If no page ID is provided, try to find a page associated with the account
+    if not page_id:
+        try:
+            # Query to get pages associated with the account
+            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_id = pages_data["data"][0]["id"]
+                print(f"Using page ID: {page_id} ({pages_data['data'][0].get('name', 'Unknown')})")
+            else:
+                return json.dumps({
+                    "error": "No page ID provided and no pages found for this account",
+                    "suggestion": "Please provide a page_id parameter"
+                }, indent=2)
+        except Exception as e:
+            return json.dumps({
+                "error": "Error finding page for account",
+                "details": str(e),
+                "suggestion": "Please provide a page_id parameter"
+            }, indent=2)
+    
+    # Prepare the creative data
+    creative_data = {
+        "name": name,
+        "object_story_spec": {
+            "page_id": page_id,
+            "link_data": {
+                "image_hash": image_hash,
+                "link": link_url if link_url else "https://facebook.com"
+            }
+        }
+    }
+    
+    # Add optional parameters if provided
+    if message:
+        creative_data["object_story_spec"]["link_data"]["message"] = message
+    
+    if headline:
+        creative_data["object_story_spec"]["link_data"]["name"] = headline
+        
+    if description:
+        creative_data["object_story_spec"]["link_data"]["description"] = description
+    
+    if call_to_action_type:
+        creative_data["object_story_spec"]["link_data"]["call_to_action"] = {
+            "type": call_to_action_type
+        }
+    
+    if instagram_actor_id:
+        creative_data["instagram_actor_id"] = instagram_actor_id
+    
+    # Prepare the API endpoint for creating a creative
+    endpoint = f"{account_id}/adcreatives"
+    
+    try:
+        # Make API request to create the creative
+        data = await make_api_request(endpoint, access_token, creative_data, method="POST")
+        
+        # If successful, get more details about the created creative
+        if "id" in data:
+            creative_id = data["id"]
+            creative_endpoint = f"{creative_id}"
+            creative_params = {
+                "fields": "id,name,status,thumbnail_url,image_url,image_hash,object_story_spec,url_tags,link_url"
+            }
+            
+            creative_details = await make_api_request(creative_endpoint, access_token, creative_params)
+            return json.dumps({
+                "success": True,
+                "creative_id": creative_id,
+                "details": creative_details
+            }, indent=2)
+        
+        return json.dumps(data, indent=2)
+    
+    except Exception as e:
+        return json.dumps({
+            "error": "Failed to create ad creative",
+            "details": str(e),
+            "creative_data_sent": creative_data
+        }, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_account_pages(access_token: str = None, account_id: str = None) -> str:
+    """
+    Get pages associated with a Meta Ads account.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+    
+    Returns:
+        JSON response with pages associated with the account
+    """
+    # Check required parameters
+    if not account_id:
+        return json.dumps({"error": "No account ID provided"}, indent=2)
+    
+    # Handle special case for 'me'
+    if account_id == "me":
+        try:
+            endpoint = "me/accounts"
+            params = {
+                "fields": "id,name,username,category,fan_count,link,verification_status,picture"
+            }
+            
+            user_pages_data = await make_api_request(endpoint, access_token, params)
+            return json.dumps(user_pages_data, indent=2)
+        except Exception as e:
+            return json.dumps({
+                "error": "Failed to get user pages",
+                "details": str(e)
+            }, indent=2)
+    
+    # Ensure account_id has the 'act_' prefix for regular accounts
+    if not account_id.startswith("act_"):
+        account_id = f"act_{account_id}"
+    
+    try:
+        # Try all approaches that might work
+        
+        # Approach 1: Get active ads and extract page IDs
+        endpoint = f"{account_id}/ads"
+        params = {
+            "fields": "creative{object_story_spec{page_id}}",
+            "limit": 100
+        }
+        
+        ads_data = await make_api_request(endpoint, access_token, params)
+        
+        # Extract unique page IDs from ads
+        page_ids = set()
+        if "data" in ads_data:
+            for ad in ads_data.get("data", []):
+                if "creative" in ad and "creative" in ad and "object_story_spec" in ad["creative"] and "page_id" in ad["creative"]["object_story_spec"]:
+                    page_ids.add(ad["creative"]["object_story_spec"]["page_id"])
+        
+        # If we found page IDs, get details for each
+        if page_ids:
+            page_details = {"data": []}
+            
+            for page_id in page_ids:
+                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:
+                    page_details["data"].append(page_data)
+            
+            if page_details["data"]:
+                return json.dumps(page_details, indent=2)
+        
+        # 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"]:
+            return json.dumps(client_pages_data, indent=2)
+        
+        # Approach 3: Try promoted_objects endpoint to find page IDs
+        endpoint = f"{account_id}/promoted_objects"
+        params = {
+            "fields": "page_id"
+        }
+        
+        promoted_objects_data = await make_api_request(endpoint, access_token, params)
+        
+        if "data" in promoted_objects_data and promoted_objects_data["data"]:
+            page_ids = set()
+            for obj in promoted_objects_data["data"]:
+                if "page_id" in obj:
+                    page_ids.add(obj["page_id"])
+            
+            if page_ids:
+                page_details = {"data": []}
+                for page_id in page_ids:
+                    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:
+                        page_details["data"].append(page_data)
+                
+                if page_details["data"]:
+                    return json.dumps(page_details, indent=2)
+        
+        # If all approaches failed, return empty data with a message
+        return json.dumps({
+            "data": [],
+            "message": "No pages found associated with this account",
+            "suggestion": "You may need to create a page or provide a page_id explicitly when creating ads"
+        }, indent=2)
+        
+    except Exception as e:
+        return json.dumps({
+            "error": "Failed to get account pages",
+            "details": str(e)
+        }, indent=2)

meta_ads_mcp/core/ads_library.py

@@ -0,0 +1,69 @@
+"""Adds Library-related 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_ads_archive(
+    access_token: str = None,
+    search_terms: str = None,
+    ad_type: str = "ALL",
+    ad_reached_countries: List[str] = None,
+    limit: int = 25,  # Default limit, adjust as needed
+    fields: str = "ad_creation_time,ad_creative_body,ad_creative_link_caption,ad_creative_link_description,ad_creative_link_title,ad_delivery_start_time,ad_delivery_stop_time,ad_snapshot_url,currency,demographic_distribution,funding_entity,impressions,page_id,page_name,publisher_platform,region_distribution,spend"
+) -> str:
+    """
+    Search the Facebook Ads Library archive.
+
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided).
+        search_terms: The search query for ads.
+        ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
+        ad_reached_countries: List of country codes (e.g., ["US", "GB"]).
+        limit: Maximum number of ads to return.
+        fields: Comma-separated string of fields to retrieve for each ad.
+
+    Example Usage via curl equivalent:
+        curl -G \\
+        -d "search_terms='california'" \\
+        -d "ad_type=POLITICAL_AND_ISSUE_ADS" \\
+        -d "ad_reached_countries=['US']" \\
+        -d "fields=ad_snapshot_url,spend" \\
+        -d "access_token=<ACCESS_TOKEN>" \\
+        "https://graph.facebook.com/<API_VERSION>/ads_archive"
+    """
+    if not access_token:
+        # Attempt to get token implicitly if not provided - meta_api_tool handles this
+        pass
+
+    if not search_terms:
+        return json.dumps({"error": "search_terms parameter is required"}, indent=2)
+
+    if not ad_reached_countries:
+        return json.dumps({"error": "ad_reached_countries parameter is required"}, indent=2)
+
+    endpoint = "ads_archive"
+    params = {
+        "search_terms": search_terms,
+        "ad_type": ad_type,
+        "ad_reached_countries": json.dumps(ad_reached_countries), # API expects a JSON array string
+        "limit": limit,
+        "fields": fields,
+    }
+
+    try:
+        data = await make_api_request(endpoint, access_token, params, method="GET")
+        return json.dumps(data, indent=2)
+    except Exception as e:
+        error_msg = str(e)
+        # Consider logging the full error for debugging
+        # print(f"Error calling Ads Library API: {error_msg}")
+        return json.dumps({
+            "error": "Failed to search ads archive",
+            "details": error_msg,
+            "params_sent": {k: v for k, v in params.items() if k != 'access_token'} # Avoid logging token
+        }, indent=2) 

meta_ads_mcp/core/budget_schedules.py

@@ -0,0 +1,71 @@
+"""Budget Schedule-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Dict, Any
+
+from .api import meta_api_tool, make_api_request
+from .server import mcp_server
+# Assuming no other specific dependencies from adsets.py are needed for this single function.
+# If other utilities from adsets.py (like get_ad_accounts) were needed, they'd be imported here.
+
+@mcp_server.tool()
+@meta_api_tool
+async def create_budget_schedule(
+    campaign_id: str,
+    budget_value: int,
+    budget_value_type: str,
+    time_start: int,
+    time_end: int,
+    access_token: str = None
+) -> str:
+    """
+    Create a budget schedule for a Meta Ads campaign.
+
+    Allows scheduling budget increases based on anticipated high-demand periods.
+    The times should be provided as Unix timestamps.
+    
+    Args:
+        campaign_id: Meta Ads campaign ID.
+        budget_value: Amount of budget increase. Interpreted based on budget_value_type.
+        budget_value_type: Type of budget value - "ABSOLUTE" or "MULTIPLIER".
+        time_start: Unix timestamp for when the high demand period should start.
+        time_end: Unix timestamp for when the high demand period should end.
+        access_token: Meta API access token (optional - will use cached token if not provided).
+        
+    Returns:
+        A JSON string containing the ID of the created budget schedule or an error message.
+    """
+    if not campaign_id:
+        return json.dumps({"error": "Campaign ID is required"}, indent=2)
+    if budget_value is None: # Check for None explicitly
+        return json.dumps({"error": "Budget value is required"}, indent=2)
+    if not budget_value_type:
+        return json.dumps({"error": "Budget value type is required"}, indent=2)
+    if budget_value_type not in ["ABSOLUTE", "MULTIPLIER"]:
+        return json.dumps({"error": "Invalid budget_value_type. Must be ABSOLUTE or MULTIPLIER"}, indent=2)
+    if time_start is None: # Check for None explicitly to allow 0
+        return json.dumps({"error": "Time start is required"}, indent=2)
+    if time_end is None: # Check for None explicitly to allow 0
+        return json.dumps({"error": "Time end is required"}, indent=2)
+
+    endpoint = f"{campaign_id}/budget_schedules"
+
+    params = {
+        "budget_value": budget_value,
+        "budget_value_type": budget_value_type,
+        "time_start": time_start,
+        "time_end": time_end,
+    }
+
+    try:
+        data = await make_api_request(endpoint, access_token, params, method="POST")
+        return json.dumps(data, indent=2)
+    except Exception as e:
+        error_msg = str(e)
+        # Include details about the error and the parameters sent for easier debugging
+        return json.dumps({
+            "error": "Failed to create budget schedule",
+            "details": error_msg,
+            "campaign_id": campaign_id,
+            "params_sent": params
+        }, indent=2) 

meta_ads_mcp/core/campaigns.py

@@ -23,7 +23,9 @@ async def get_campaigns(access_token: str = None, account_id: str = None, limit:
         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 campaigns to return (default: 10)
-        status_filter: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
+        status_filter: Filter by effective status (e.g., 'ACTIVE', 'PAUSED', 'ARCHIVED').
+                       Maps to the 'effective_status' API parameter, which expects an array
+                       (this function handles the required JSON formatting). Leave empty for all statuses.
     """
     # If no account ID is specified, try to get the first one for the user
     if not account_id:
@@ -42,7 +44,8 @@ async def get_campaigns(access_token: str = None, account_id: str = None, limit:
     }
     
     if status_filter:
-        params["effective_status"] = status_filter
+        # API expects an array, encode it as a JSON string
+        params["effective_status"] = json.dumps([status_filter])
     
     data = await make_api_request(endpoint, access_token, params)
     

{meta_ads_mcp-0.3.2.dist-info → meta_ads_mcp-0.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.3.2
+Version: 0.3.5
 Summary: Model Calling Protocol (MCP) plugin for interacting with Meta Ads API
 Project-URL: Homepage, https://github.com/nictuku/meta-ads-mcp
 Project-URL: Bug Tracker, https://github.com/nictuku/meta-ads-mcp/issues
@@ -11,7 +11,7 @@ Keywords: ads,api,claude,facebook,mcp,meta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.11
+Requires-Python: >=3.9.6
 Requires-Dist: httpx>=0.26.0
 Requires-Dist: mcp[cli]>=1.6.0
 Requires-Dist: pathlib>=1.0.1
@@ -27,11 +27,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 
 > **DISCLAIMER:** This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.
 
-<a href="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp/badge" alt="Meta Ads MCP server" />
-</a>
-
-Screenshot: using an LLM to understand your ad performance.
+**Screenshot**: Using an LLM to understand your ad performance:
 
 ![Meta Ads MCP in action: Visualize ad performance metrics and creative details directly in Claude or your favorite MCP client, with rich insights about campaign reach, engagement, and costs](./images/meta-ads-example.png)
 
@@ -94,7 +90,7 @@ python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
 Before using the MCP server, you'll need to set up a Meta Developer App:
 
 1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
-2. Choose the "Consumer" app type
+2. Choose the "Business" app type
 3. In your app settings, add the "Marketing API" product
 4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
 5. Note your App ID (Client ID) for use with the MCP
@@ -129,7 +125,14 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
    - Returns: Detailed information about the specified account
 
-3. `mcp_meta_ads_get_campaigns`
+3. `mcp_meta_ads_get_account_pages`
+   - Get pages associated with a Meta Ads account
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX) or "me" for the current user's pages
+   - Returns: List of pages associated with the account, useful for ad creation and management
+
+4. `mcp_meta_ads_get_campaigns`
    - Get campaigns for a Meta Ads account with optional filtering
    - Inputs:
      - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -138,14 +141,14 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
      - `status_filter`: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
    - Returns: List of campaigns matching the criteria
 
-4. `mcp_meta_ads_get_campaign_details`
+5. `mcp_meta_ads_get_campaign_details`
    - Get detailed information about a specific campaign
    - Inputs:
      - `access_token` (optional): Meta API access token (will use cached token if not provided)
      - `campaign_id`: Meta Ads campaign ID
    - Returns: Detailed information about the specified campaign
 
-5. `mcp_meta_ads_create_campaign`
+6. `mcp_meta_ads_create_campaign`
    - Create a new campaign in a Meta Ads account
    - Inputs:
      - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -158,7 +161,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
      - `lifetime_budget`: Lifetime budget in account currency (in cents)
    - Returns: Confirmation with new campaign details
 
-6. `mcp_meta_ads_get_adsets`
+7. `mcp_meta_ads_get_adsets`
    - Get ad sets for a Meta Ads account with optional filtering by campaign
    - Inputs:
      - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -167,45 +170,101 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
      - `campaign_id`: Optional campaign ID to filter by
    - Returns: List of ad sets matching the criteria
 
-7. `mcp_meta_ads_get_adset_details`
+8. `mcp_meta_ads_get_adset_details`
    - Get detailed information about a specific ad set
    - Inputs:
      - `access_token` (optional): Meta API access token (will use cached token if not provided)
      - `adset_id`: Meta Ads ad set ID
    - Returns: Detailed information about the specified ad set
 
-8. `mcp_meta_ads_get_ads`
-   - Get ads for a Meta Ads account with optional filtering
+9. `mcp_meta_ads_create_adset`
+   - Create a new ad set in a Meta Ads account
    - Inputs:
-     - `access_token` (optional): Meta API access token (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
-   - Returns: List of ads matching the criteria
-
-9. `mcp_meta_ads_get_ad_details`
-   - Get detailed information about a specific ad
-   - Inputs:
-     - `access_token` (optional): Meta API access token (will use cached token if not provided)
-     - `ad_id`: Meta Ads ad ID
-   - Returns: Detailed information about the specified ad
+     - `campaign_id`: Meta Ads campaign ID this ad set belongs to
+     - `name`: Ad set name
+     - `status`: Initial ad set status (default: PAUSED)
+     - `daily_budget`: Daily budget in account currency (in cents) as a string
+     - `lifetime_budget`: Lifetime budget in account currency (in cents) as a string
+     - `targeting`: Targeting specifications (e.g., age, location, interests)
+     - `optimization_goal`: Conversion optimization goal (e.g., 'LINK_CLICKS')
+     - `billing_event`: How you're charged (e.g., 'IMPRESSIONS')
+     - `bid_amount`: Bid amount in account currency (in cents)
+     - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST')
+     - `start_time`, `end_time`: Optional start/end times (ISO 8601)
+     - `access_token` (optional): Meta API access token
+   - Returns: Confirmation with new ad set details
+
+10. `mcp_meta_ads_get_ads`
+    - Get ads for a Meta Ads account with optional filtering
+    - Inputs:
+      - `access_token` (optional): Meta API access token (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
+    - Returns: List of ads matching the criteria
+
+11. `mcp_meta_ads_create_ad`
+    - Create a new ad with an existing creative
+    - Inputs:
+      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+      - `name`: Ad name
+      - `adset_id`: Ad set ID where this ad will be placed
+      - `creative_id`: ID of an existing creative to use
+      - `status`: Initial ad status (default: PAUSED)
+      - `bid_amount`: Optional bid amount (in cents)
+      - `tracking_specs`: Optional tracking specifications
+      - `access_token` (optional): Meta API access token
+    - Returns: Confirmation with new ad details
+
+12. `mcp_meta_ads_get_ad_details`
+    - Get detailed information about a specific ad
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `ad_id`: Meta Ads ad ID
+    - Returns: Detailed information about the specified ad
 
-10. `mcp_meta_ads_get_ad_creatives`
+13. `mcp_meta_ads_get_ad_creatives`
     - Get creative details for a specific ad
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
       - `ad_id`: Meta Ads ad ID
     - Returns: Creative details including text, images, and URLs
 
-11. `mcp_meta_ads_get_ad_image`
+14. `mcp_meta_ads_create_ad_creative`
+    - Create a new ad creative using an uploaded image hash
+    - Inputs:
+      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+      - `name`: Creative name
+      - `image_hash`: Hash of the uploaded image
+      - `page_id`: Facebook Page ID for the ad
+      - `link_url`: Destination URL
+      - `message`: Ad copy/text
+      - `headline`: Ad headline
+      - `description`: Ad description
+      - `call_to_action_type`: CTA button type (e.g., 'LEARN_MORE')
+      - `instagram_actor_id`: Optional Instagram account ID
+      - `access_token` (optional): Meta API access token
+    - Returns: Confirmation with new creative details
+
+15. `mcp_meta_ads_upload_ad_image`
+    - Upload an image to use in Meta Ads creatives
+    - Inputs:
+      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+      - `image_path`: Path to the image file to upload
+      - `name`: Optional name for the image
+      - `access_token` (optional): Meta API access token
+    - Returns: JSON response with image details including hash
+
+16. `mcp_meta_ads_get_ad_image`
     - Get, download, and visualize a Meta ad image in one step
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
       - `ad_id`: Meta Ads ad ID
     - Returns: The ad image ready for direct visual analysis
 
-12. `mcp_meta_ads_update_ad`
+17. `mcp_meta_ads_update_ad`
     - Update an ad with new settings
     - Inputs:
       - `ad_id`: Meta Ads ad ID
@@ -214,7 +273,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: Confirmation with updated ad details and a confirmation link
 
-13. `mcp_meta_ads_update_adset`
+18. `mcp_meta_ads_update_adset`
     - Update an ad set with new settings including frequency caps
     - Inputs:
       - `adset_id`: Meta Ads ad set ID
@@ -226,7 +285,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: Confirmation with updated ad set details and a confirmation link
 
-14. `mcp_meta_ads_get_insights`
+19. `mcp_meta_ads_get_insights`
     - Get performance insights for a campaign, ad set, ad or account
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -236,7 +295,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `level`: Level of aggregation (ad, adset, campaign, account)
     - Returns: Performance metrics for the specified object
 
-15. `mcp_meta_ads_debug_image_download`
+20. `mcp_meta_ads_debug_image_download`
     - Debug image download issues and report detailed diagnostics
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -244,12 +303,23 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
     - Returns: Diagnostic information about image download attempts
 
-16. `mcp_meta_ads_get_login_link`
+21. `mcp_meta_ads_get_login_link`
     - Get a clickable login link for Meta Ads authentication
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: A clickable resource link for Meta authentication
 
+22. `mcp_meta-ads_create_budget_schedule`
+    - Create a budget schedule for a Meta Ads campaign.
+    - Inputs:
+      - `campaign_id`: Meta Ads campaign ID.
+      - `budget_value`: Amount of budget increase.
+      - `budget_value_type`: Type of budget value ("ABSOLUTE" or "MULTIPLIER").
+      - `time_start`: Unix timestamp for when the high demand period should start.
+      - `time_end`: Unix timestamp for when the high demand period should end.
+      - `access_token` (optional): Meta API access token.
+    - Returns: JSON string with the ID of the created budget schedule or an error message.
+
 ## Authentication
 
 The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:

{meta_ads_mcp-0.3.2.dist-info → meta_ads_mcp-0.3.5.dist-info}/RECORD

@@ -1,22 +1,24 @@
-meta_ads_mcp/__init__.py,sha256=Xa5R_8nWJqcRh6Jps90mcuihcp4bJDKGXGg1bwnoSz4,1236
+meta_ads_mcp/__init__.py,sha256=RSDlsZrR_mt2PklzoAeG_4555QHPTM1ZJrvr5aVadjU,1236
 meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
 meta_ads_mcp/api.py,sha256=z0pW1pV3hE75IeG9QTqB3K7QoQOUxUg2MBQ9IjAWUYA,84363
-meta_ads_mcp/core/__init__.py,sha256=6T8iqrQrw9VHhKtncLqYWyDk8jeSBPs79hs1CSu-fLU,952
+meta_ads_mcp/core/__init__.py,sha256=NvRA_socbKPEXFXIYdso5jBHb8cEEpF_2Mwhe3Obguw,1105
 meta_ads_mcp/core/accounts.py,sha256=Nmp7lPxO9wmq25jWV7_H0LIqnEbBhpCVBlLGW2HUaq0,2277
-meta_ads_mcp/core/ads.py,sha256=LMZOo6agi6tQl4JJPmrDUn-91n7DzfxG2TChmwcrWOY,12544
+meta_ads_mcp/core/ads.py,sha256=b_81GlGHIM4jISvuDZmHNyc6uW7uD3ovX68ezBci9MM,29747
+meta_ads_mcp/core/ads_library.py,sha256=onStn9UkRqYDC60gOPS-iKDtP1plz6DygUb7hUZ0Jw8,2807
 meta_ads_mcp/core/adsets.py,sha256=WBPNaI7ITnUOnGMus4_0MX15DslOCzfM5q1zF1VWs2s,12408
 meta_ads_mcp/core/api.py,sha256=9Whcs2orILhPiWkAR3qGmJNouYE5uri_e_Jzeh5Hjn8,14208
 meta_ads_mcp/core/auth.py,sha256=pDARBh3NBNqCpxflVrVvR4VsWuIveFxQmb9-P-gLFDM,20730
 meta_ads_mcp/core/authentication.py,sha256=2MG13r28OlIcOIgPSRrGXJ2-4JSt3ifU-oB9tiOsrKQ,6511
+meta_ads_mcp/core/budget_schedules.py,sha256=UxseExsvKAiPwfDCY9aycT4kys4xqeNytyq-yyDOxrs,2901
 meta_ads_mcp/core/callback_server.py,sha256=AUymElaVwHqFyqB2wgqf6A68KsqwtKoYmY-7JZZt8Ks,43286
-meta_ads_mcp/core/campaigns.py,sha256=20DHMwHppZuoZBg0owkf1BfmPBhWzkQcFgh5rQa-pAU,10480
+meta_ads_mcp/core/campaigns.py,sha256=TQHDhJ0s7cLbo5-zd2Bk8YgwToWBoK3YBMFG8fZbEHI,10757
 meta_ads_mcp/core/insights.py,sha256=XAm4uu83gWp84PEGqAJ3GFIqlvg7prh6MdD71JfvBCo,18072
 meta_ads_mcp/core/pipeboard_auth.py,sha256=VvbxEB8ZOhnMccLU7HI1HgaPWHCl5NGrzZCm-zzHze4,22798
 meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
 meta_ads_mcp/core/server.py,sha256=5WofyJZGzeDhbGzLXPhQjT0XnZwo0syeK8TM_XnJo4Q,5507
 meta_ads_mcp/core/utils.py,sha256=EPmpBX3OZaTWRS_YuEk_PLLyLXj7DeR6Ks8WoaZ5JGQ,6366
-meta_ads_mcp-0.3.2.dist-info/METADATA,sha256=Q_05xZMow3h9ova-mvfiL210rWvy-Ix9B_sZEetjN4k,16212
-meta_ads_mcp-0.3.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.3.2.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.3.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-meta_ads_mcp-0.3.2.dist-info/RECORD,,
+meta_ads_mcp-0.3.5.dist-info/METADATA,sha256=lbTJVtr81f-WwPI87zeKUKqGe0HzZrlC5c-WJeZKv2c,19650
+meta_ads_mcp-0.3.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.3.5.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.3.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+meta_ads_mcp-0.3.5.dist-info/RECORD,,