meta-ads-mcp 0.2.1__tar.gz → 0.2.3__tar.gz

{meta_ads_mcp-0.2.1 → meta_ads_mcp-0.2.3}/.gitignore

@@ -10,3 +10,13 @@ wheels/
 .venv
 .cursor/rules/meta-ads-credentials.mdc
 .DS_Store
+
+# Development environment files
+.python-version
+poetry.lock
+uv.lock
+.uv.toml
+.cursor/
+
+# Generated content
+ad_creatives/

{meta_ads_mcp-0.2.1 → meta_ads_mcp-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.2.1
+Version: 0.2.3
 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

meta_ads_mcp-0.2.3/future_improvements.md

@@ -0,0 +1,59 @@
+# Future Improvements for Meta Ads MCP
+
+## Planned Improvement: Refactored meta_ads_generated.py
+
+This file currently has too much code and it needs to be split into a small number of modules.
+
+## Planned Improvement: Ad Set Update Confirmation Flow
+
+### Overview
+Currently, the `update_adset` function directly applies changes to Meta Ad Sets without user confirmation. This is potentially risky as users may not fully understand the impact of their changes before they're applied. We plan to implement a confirmation flow similar to the authentication flow that already exists for the `get_login_link` function.
+
+### Requirements
+
+1. **Local Confirmation Server:**
+   - Leverage the existing local HTTP server infrastructure used for authentication
+   - Create a new endpoint at `/confirm-update` to display proposed changes
+   - Ensure the server can handle multiple types of confirmation flows
+
+2. **Update Flow:**
+   - When `update_adset` is called, it will:
+     - Fetch the current ad set details to establish a baseline
+     - Generate a diff between current and proposed changes
+     - Return a clickable link to a local confirmation page instead of making immediate changes
+   
+3. **Confirmation UI:**
+   - Display ad set name and ID clearly at the top
+   - Show a side-by-side or diff view of the current vs. proposed settings
+   - Highlight specific changes (e.g., bid amount, bid strategy, status changes)
+   - Provide "Approve" and "Cancel" buttons
+   - Include a warning about potential billing impact for status changes
+
+4. **Security Considerations:**
+   - Ensure that confirmation links have a short expiration time
+   - Generate unique tokens for each confirmation request to prevent replays
+   - Log all confirmation activities
+
+5. **Response Handling:**
+   - If approved, execute the original update API call
+   - Return a success message with details of the changes applied
+   - If rejected, return a cancellation message
+   - Either way, provide detailed information to the user
+
+6. **Implementation Timeline:**
+   - Phase 1: Implement the basic confirmation flow structure
+   - Phase 2: Add improved diff visualization
+   - Phase 3: Extend to other modification functions (campaigns, ads, etc.)
+
+### Implementation Notes
+
+The implementation will reuse much of the callback server infrastructure that already exists for authentication, adapting it to support this new use case. The confirmation page will be a simple HTML/JS application that can:
+
+1. Parse URL parameters containing update details
+2. Fetch current ad set state using the provided access token
+3. Generate and display a visual diff
+4. Send the confirmation back to the server via API call
+
+By ensuring changes are confirmed before execution, we'll significantly reduce the risk of accidental modifications to ad campaigns while maintaining the flexibility and power of the Meta Ads MCP.
+
+Future improvements can be added to this file as needed. 

meta_ads_mcp-0.2.3/meta-ads-mcp

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Meta Ads MCP - Command Line Entry Point
+
+This script provides the command-line entry point for the Meta Ads MCP package.
+"""
+
+from meta_ads_mcp import main
+
+if __name__ == "__main__":
+    print("RUNNING LOCAL SCRIPT VERSION OF META ADS MCP")
+    main() 

{meta_ads_mcp-0.2.1 → meta_ads_mcp-0.2.3}/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-0.2.3/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-0.2.3/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-0.2.3/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-0.2.3/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)}"