meta-ads-mcp 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

meta_ads_mcp/__init__.py

@@ -1,9 +1,18 @@
-"""Meta Ads MCP - Model Calling Protocol plugin for Meta Ads API."""
+"""
+Meta Ads MCP - Python Package
 
-__version__ = "0.2.1"
+This package provides a Meta Ads Marketing Cloud Platform (MCP) integration
+with the Claude LLM.
+"""
+
+from meta_ads_mcp.core.server import main
+
+__version__ = "0.2.3"
+
+__all__ = ["main"]
 
 # Import key functions to make them available at package level
-from .api import (
+from .core import (
     get_ad_accounts,
     get_account_info,
     get_campaigns,
@@ -11,17 +20,22 @@ from .api import (
     create_campaign,
     get_adsets,
     get_adset_details,
+    update_adset,
     get_ads,
     get_ad_details,
     get_ad_creatives,
     get_ad_image,
     get_insights,
+    debug_image_download,
+    save_ad_image_via_api,
     get_login_link,
     login_cli,
-    main,  # Import main function for entry point
 )
 
 # Define a main function to be used as a package entry point
 def entrypoint():
     """Main entry point for the package when invoked with uvx."""
-    return main() 
+    return main() 
+
+# Re-export main for direct access
+main = main 

meta_ads_mcp/__main__.py

@@ -0,0 +1,10 @@
+"""
+Meta Ads MCP - Main Entry Point
+
+This module allows the package to be executed directly via `python -m meta_ads_mcp`
+"""
+
+from meta_ads_mcp.core.server import main
+
+if __name__ == "__main__":
+    main() 

meta_ads_mcp/core/__init__.py

@@ -0,0 +1,34 @@
+"""Core functionality for Meta Ads API MCP package."""
+
+from .server import mcp_server
+from .accounts import get_ad_accounts, get_account_info
+from .campaigns import get_campaigns, get_campaign_details, create_campaign
+from .adsets import get_adsets, get_adset_details, update_adset
+from .ads import get_ads, get_ad_details, get_ad_creatives, get_ad_image
+from .insights import get_insights, debug_image_download, save_ad_image_via_api
+from .authentication import get_login_link
+from .server import login_cli, main
+from .auth import login
+
+__all__ = [
+    'mcp_server',
+    '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',
+    'get_insights',
+    'debug_image_download',
+    'save_ad_image_via_api',
+    'get_login_link',
+    'login_cli',
+    'login',
+    'main',
+] 

meta_ads_mcp/core/accounts.py

@@ -0,0 +1,59 @@
+"""Account-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional
+from .api import meta_api_tool, make_api_request
+
+
+@meta_api_tool
+async def get_ad_accounts(access_token: str = None, user_id: str = "me", limit: int = 10) -> str:
+    """
+    Get ad accounts accessible by a user.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        user_id: Meta user ID or "me" for the current user
+        limit: Maximum number of accounts to return (default: 10)
+    """
+    endpoint = f"{user_id}/adaccounts"
+    params = {
+        "fields": "id,name,account_id,account_status,amount_spent,balance,currency,age,business_city,business_country_code",
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@meta_api_tool
+async def get_account_info(access_token: str = None, account_id: str = None) -> str:
+    """
+    Get detailed information about a specific ad 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)
+    """
+    # If no account ID is specified, try to get the first one for the user
+    if not account_id:
+        accounts_json = await get_ad_accounts("me", json.dumps({"limit": 1}), access_token)
+        accounts_data = json.loads(accounts_json)
+        
+        if "data" in accounts_data and accounts_data["data"]:
+            account_id = accounts_data["data"][0]["id"]
+        else:
+            return json.dumps({"error": "No account ID specified and no accounts found for user"}, indent=2)
+    
+    # Ensure account_id has the 'act_' prefix for API compatibility
+    if not account_id.startswith("act_"):
+        account_id = f"act_{account_id}"
+    
+    endpoint = f"{account_id}"
+    params = {
+        "fields": "id,name,account_id,account_status,amount_spent,balance,currency,age,funding_source_details,business_city,business_country_code,timezone_name,owner"
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2) 

meta_ads_mcp/core/ads.py

@@ -0,0 +1,361 @@
+"""Ad and Creative-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Dict, Any
+import io
+from PIL import Image as PILImage
+from mcp.server.fastmcp import Image
+
+from .api import meta_api_tool, make_api_request
+from .accounts import get_ad_accounts
+from .utils import download_image, try_multiple_download_methods, ad_creative_images
+
+
+@meta_api_tool
+async def get_ads(access_token: str = None, account_id: str = None, limit: int = 10, 
+                 campaign_id: str = "", adset_id: str = "") -> str:
+    """
+    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
+    """
+    # If no account ID is specified, try to get the first one for the user
+    if not account_id:
+        accounts_json = await get_ad_accounts("me", json.dumps({"limit": 1}), access_token)
+        accounts_data = json.loads(accounts_json)
+        
+        if "data" in accounts_data and accounts_data["data"]:
+            account_id = accounts_data["data"][0]["id"]
+        else:
+            return json.dumps({"error": "No account ID specified and no accounts found for user"}, indent=2)
+    
+    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
+    }
+    
+    if campaign_id:
+        params["campaign_id"] = campaign_id
+    
+    if adset_id:
+        params["adset_id"] = adset_id
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@meta_api_tool
+async def get_ad_details(access_token: str = None, ad_id: str = None) -> str:
+    """
+    Get detailed information about a specific ad.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+    """
+    if not ad_id:
+        return json.dumps({"error": "No ad ID provided"}, indent=2)
+        
+    endpoint = f"{ad_id}"
+    params = {
+        "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs,preview_shareable_link"
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@meta_api_tool
+async def get_ad_creatives(access_token: str = None, ad_id: str = None) -> str:
+    """
+    Get creative details for a specific ad. Best if combined with get_ad_image to get the full image.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+    """
+    if not ad_id:
+        return json.dumps({"error": "No ad ID provided"}, indent=2)
+        
+    # First, get the creative ID from the ad
+    endpoint = f"{ad_id}"
+    params = {
+        "fields": "creative"
+    }
+    
+    ad_data = await make_api_request(endpoint, access_token, params)
+    
+    if "error" in ad_data:
+        return json.dumps(ad_data, indent=2)
+    
+    if "creative" not in ad_data:
+        return json.dumps({"error": "No creative found for this ad"}, indent=2)
+    
+    creative_id = ad_data.get("creative", {}).get("id")
+    if not creative_id:
+        return json.dumps({"error": "Creative ID not found", "ad_data": ad_data}, indent=2)
+    
+    # Now get the creative details with essential fields
+    creative_endpoint = f"{creative_id}"
+    creative_params = {
+        "fields": "id,name,title,body,image_url,object_story_spec,url_tags,link_url,thumbnail_url,image_hash,asset_feed_spec,object_type"
+    }
+    
+    creative_data = await make_api_request(creative_endpoint, access_token, creative_params)
+    
+    # Try to get full-size images in different ways:
+    
+    # 1. First approach: Get ad images directly using the adimages endpoint
+    if "image_hash" in creative_data:
+        image_hash = creative_data.get("image_hash")
+        image_endpoint = f"act_{ad_data.get('account_id', '')}/adimages"
+        image_params = {
+            "hashes": [image_hash]
+        }
+        image_data = await make_api_request(image_endpoint, access_token, image_params)
+        if "data" in image_data and len(image_data["data"]) > 0:
+            creative_data["full_image_url"] = image_data["data"][0].get("url")
+    
+    # 2. For creatives with object_story_spec
+    if "object_story_spec" in creative_data:
+        spec = creative_data.get("object_story_spec", {})
+        
+        # For link ads
+        if "link_data" in spec:
+            link_data = spec.get("link_data", {})
+            # If there's an explicit image_url, use it
+            if "image_url" in link_data:
+                creative_data["full_image_url"] = link_data.get("image_url")
+            # If there's an image_hash, try to get the full image
+            elif "image_hash" in link_data:
+                image_hash = link_data.get("image_hash")
+                account_id = ad_data.get('account_id', '')
+                if not account_id:
+                    # Try to get account ID from ad ID
+                    ad_details_endpoint = f"{ad_id}"
+                    ad_details_params = {
+                        "fields": "account_id"
+                    }
+                    ad_details = await make_api_request(ad_details_endpoint, access_token, ad_details_params)
+                    account_id = ad_details.get('account_id', '')
+                
+                if account_id:
+                    image_endpoint = f"act_{account_id}/adimages"
+                    image_params = {
+                        "hashes": [image_hash]
+                    }
+                    image_data = await make_api_request(image_endpoint, access_token, image_params)
+                    if "data" in image_data and len(image_data["data"]) > 0:
+                        creative_data["full_image_url"] = image_data["data"][0].get("url")
+        
+        # For photo ads
+        if "photo_data" in spec:
+            photo_data = spec.get("photo_data", {})
+            if "image_hash" in photo_data:
+                image_hash = photo_data.get("image_hash")
+                account_id = ad_data.get('account_id', '')
+                if not account_id:
+                    # Try to get account ID from ad ID
+                    ad_details_endpoint = f"{ad_id}"
+                    ad_details_params = {
+                        "fields": "account_id"
+                    }
+                    ad_details = await make_api_request(ad_details_endpoint, access_token, ad_details_params)
+                    account_id = ad_details.get('account_id', '')
+                
+                if account_id:
+                    image_endpoint = f"act_{account_id}/adimages"
+                    image_params = {
+                        "hashes": [image_hash]
+                    }
+                    image_data = await make_api_request(image_endpoint, access_token, image_params)
+                    if "data" in image_data and len(image_data["data"]) > 0:
+                        creative_data["full_image_url"] = image_data["data"][0].get("url")
+    
+    # 3. If there's an asset_feed_spec, try to get images from there
+    if "asset_feed_spec" in creative_data and "images" in creative_data["asset_feed_spec"]:
+        images = creative_data["asset_feed_spec"]["images"]
+        if images and len(images) > 0 and "hash" in images[0]:
+            image_hash = images[0]["hash"]
+            account_id = ad_data.get('account_id', '')
+            if not account_id:
+                # Try to get account ID
+                ad_details_endpoint = f"{ad_id}"
+                ad_details_params = {
+                    "fields": "account_id"
+                }
+                ad_details = await make_api_request(ad_details_endpoint, access_token, ad_details_params)
+                account_id = ad_details.get('account_id', '')
+            
+            if account_id:
+                image_endpoint = f"act_{account_id}/adimages"
+                image_params = {
+                    "hashes": [image_hash]
+                }
+                image_data = await make_api_request(image_endpoint, access_token, image_params)
+                if "data" in image_data and len(image_data["data"]) > 0:
+                    creative_data["full_image_url"] = image_data["data"][0].get("url")
+    
+    # If we have a thumbnail_url but no full_image_url, let's attempt to convert the thumbnail URL to full size
+    if "thumbnail_url" in creative_data and "full_image_url" not in creative_data:
+        thumbnail_url = creative_data["thumbnail_url"]
+        # Try to convert the URL to get higher resolution by removing size parameters
+        if "p64x64" in thumbnail_url:
+            full_url = thumbnail_url.replace("p64x64", "p1080x1080")
+            creative_data["full_image_url"] = full_url
+        elif "dst-emg0" in thumbnail_url:
+            # Remove the dst-emg0 parameter that seems to reduce size
+            full_url = thumbnail_url.replace("dst-emg0_", "")
+            creative_data["full_image_url"] = full_url
+    
+    # Fallback to using thumbnail or image_url if we still don't have a full image
+    if "full_image_url" not in creative_data:
+        if "thumbnail_url" in creative_data:
+            creative_data["full_image_url"] = creative_data["thumbnail_url"]
+        elif "image_url" in creative_data:
+            creative_data["full_image_url"] = creative_data["image_url"]
+    
+    return json.dumps(creative_data, indent=2)
+
+
+@meta_api_tool
+async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
+    """
+    Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+    
+    Returns:
+        The ad image ready for direct visual analysis
+    """
+    if not ad_id:
+        return "Error: No ad ID provided"
+        
+    print(f"Attempting to get and analyze 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 f"Error: Could not get ad data - {json.dumps(ad_data)}"
+    
+    # Extract account_id
+    account_id = ad_data.get("account_id", "")
+    if not account_id:
+        return "Error: No account ID found"
+    
+    # Extract creative ID
+    if "creative" not in ad_data:
+        return "Error: No creative found for this ad"
+        
+    creative_data = ad_data.get("creative", {})
+    creative_id = creative_data.get("id")
+    if not creative_id:
+        return "Error: No creative ID found"
+    
+    # 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)
+    
+    # Identify image hashes to use from creative
+    image_hashes = []
+    
+    # Check for direct image_hash on creative
+    if "image_hash" in creative_details:
+        image_hashes.append(creative_details["image_hash"])
+    
+    # Check asset_feed_spec for image hashes - common in Advantage+ ads
+    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:
+        # If no hashes found, try to extract from the first creative we found in the API
+        # Get creative for ad to try to extract hash
+        creative_json = await get_ad_creatives(ad_id, "", access_token)
+        creative_data = json.loads(creative_json)
+        
+        # Try to extract hash from asset_feed_spec
+        if "asset_feed_spec" in creative_data and "images" in creative_data["asset_feed_spec"]:
+            images = creative_data["asset_feed_spec"]["images"]
+            if images and len(images) > 0 and "hash" in images[0]:
+                image_hashes.append(images[0]["hash"])
+    
+    if not image_hashes:
+        return "Error: No image hashes found in creative"
+    
+    print(f"Found image hashes: {image_hashes}")
+    
+    # Now fetch image data using adimages endpoint with specific format
+    image_endpoint = f"act_{account_id}/adimages"
+    
+    # Format the hashes parameter exactly as in our successful curl test
+    hashes_str = f'["{image_hashes[0]}"]'  # Format first hash only, as JSON string array
+    
+    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 f"Error: Failed to get image data - {json.dumps(image_data)}"
+    
+    if "data" not in image_data or not image_data["data"]:
+        return "Error: No image data returned from API"
+    
+    # Get the first image URL
+    first_image = image_data["data"][0]
+    image_url = first_image.get("url")
+    
+    if not image_url:
+        return "Error: No valid image URL found"
+    
+    print(f"Downloading image from URL: {image_url}")
+    
+    # Download the image
+    image_bytes = await download_image(image_url)
+    
+    if not image_bytes:
+        return "Error: Failed to download image"
+    
+    try:
+        # Convert bytes to PIL Image
+        img = PILImage.open(io.BytesIO(image_bytes))
+        
+        # Convert to RGB if needed
+        if img.mode != "RGB":
+            img = img.convert("RGB")
+            
+        # Create a byte stream of the image data
+        byte_arr = io.BytesIO()
+        img.save(byte_arr, format="JPEG")
+        img_bytes = byte_arr.getvalue()
+        
+        # Return as an Image object that LLM can directly analyze
+        return Image(data=img_bytes, format="jpeg")
+        
+    except Exception as e:
+        return f"Error processing image: {str(e)}" 

meta_ads_mcp/core/adsets.py

@@ -0,0 +1,115 @@
+"""Ad Set-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Dict, Any, List
+from .api import meta_api_tool, make_api_request
+from .accounts import get_ad_accounts
+
+
+@meta_api_tool
+async def get_adsets(access_token: str = None, account_id: str = None, limit: int = 10, campaign_id: str = "") -> str:
+    """
+    Get ad sets for a Meta Ads account with optional filtering by campaign.
+    
+    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 ad sets to return (default: 10)
+        campaign_id: Optional campaign ID to filter by
+    """
+    # If no account ID is specified, try to get the first one for the user
+    if not account_id:
+        accounts_json = await get_ad_accounts("me", json.dumps({"limit": 1}), access_token)
+        accounts_data = json.loads(accounts_json)
+        
+        if "data" in accounts_data and accounts_data["data"]:
+            account_id = accounts_data["data"][0]["id"]
+        else:
+            return json.dumps({"error": "No account ID specified and no accounts found for user"}, indent=2)
+    
+    endpoint = f"{account_id}/adsets"
+    params = {
+        "fields": "id,name,campaign_id,status,daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time",
+        "limit": limit
+    }
+    
+    if campaign_id:
+        params["campaign_id"] = campaign_id
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@meta_api_tool
+async def get_adset_details(access_token: str = None, adset_id: str = None) -> str:
+    """
+    Get detailed information about a specific ad set.
+    
+    Args:
+        adset_id: Meta Ads ad set ID (required)
+        access_token: Meta API access token (optional - will use cached token if not provided)
+    
+    Example:
+        To call this function through MCP, pass the adset_id as the first argument:
+        {
+            "args": "YOUR_ADSET_ID"
+        }
+    """
+    if not adset_id:
+        return json.dumps({"error": "No ad set ID provided"}, indent=2)
+    
+    endpoint = f"{adset_id}"
+    params = {
+        "fields": "id,name,campaign_id,status,daily_budget,lifetime_budget,targeting,bid_amount,bid_strategy,optimization_goal,billing_event,start_time,end_time,created_time,updated_time,attribution_spec,destination_type,promoted_object,pacing_type,budget_remaining"
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@meta_api_tool
+async def update_adset(access_token: str = None, adset_id: str = None, 
+                       bid_strategy: Optional[str] = None, 
+                       bid_amount: Optional[int] = None,
+                       frequency_control_specs: Optional[List[Dict[str, Any]]] = None,
+                       status: Optional[str] = None) -> str:
+    """
+    Update an existing ad set with new settings including frequency caps.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        adset_id: Meta Ads ad set ID
+        bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP')
+        bid_amount: Bid amount in your account's currency (in cents for USD)
+        frequency_control_specs: List of frequency control specifications. Each spec should have:
+            - event: Type of event (e.g., 'IMPRESSIONS')
+            - interval_days: Number of days for the frequency cap
+            - max_frequency: Maximum number of times to show the ad
+        status: Update ad set status (ACTIVE, PAUSED, etc.)
+    """
+    if not adset_id:
+        return json.dumps({"error": "No ad set ID provided"}, indent=2)
+    
+    endpoint = f"{adset_id}"
+    params = {}
+    
+    if bid_strategy:
+        params["bid_strategy"] = bid_strategy
+    
+    if bid_amount is not None:
+        params["bid_amount"] = bid_amount
+    
+    if frequency_control_specs:
+        params["frequency_control_specs"] = frequency_control_specs
+    
+    if status:
+        params["status"] = status
+    
+    if not params:
+        return json.dumps({"error": "No update parameters provided"}, indent=2)
+    
+    data = await make_api_request(endpoint, access_token, params, method="POST")
+    
+    return json.dumps(data, indent=2)