meta-ads-mcp 1.0.13__py3-none-any.whl → 1.0.16__py3-none-any.whl

meta_ads_mcp/__init__.py

@@ -6,7 +6,7 @@ This package provides a Meta Ads MCP integration
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "1.0.13"
+__version__ = "1.0.16"
 
 __all__ = [
     'get_ad_accounts',

meta_ads_mcp/core/ads.py

@@ -831,32 +831,18 @@ async def create_ad_creative(
     if description and descriptions:
         return json.dumps({"error": "Cannot specify both 'description' and 'descriptions'. Use 'description' for single description or 'descriptions' for multiple."}, indent=2)
     
-    # Convert simple parameters to complex format for internal processing
-    final_headlines = None
-    final_descriptions = None
-    
-    if headline:
-        final_headlines = [headline]
-    elif headlines:
-        final_headlines = headlines
-        
-    if description:
-        final_descriptions = [description]
-    elif descriptions:
-        final_descriptions = descriptions
-    
-    # Validate dynamic creative parameters
-    if final_headlines:
-        if len(final_headlines) > 5:
+    # Validate dynamic creative parameters (plural forms only)
+    if headlines:
+        if len(headlines) > 5:
             return json.dumps({"error": "Maximum 5 headlines allowed for dynamic creatives"}, indent=2)
-        for i, h in enumerate(final_headlines):
+        for i, h in enumerate(headlines):
             if len(h) > 40:
                 return json.dumps({"error": f"Headline {i+1} exceeds 40 character limit"}, indent=2)
     
-    if final_descriptions:
-        if len(final_descriptions) > 5:
+    if descriptions:
+        if len(descriptions) > 5:
             return json.dumps({"error": "Maximum 5 descriptions allowed for dynamic creatives"}, indent=2)
-        for i, d in enumerate(final_descriptions):
+        for i, d in enumerate(descriptions):
             if len(d) > 125:
                 return json.dumps({"error": f"Description {i+1} exceeds 125 character limit"}, indent=2)
     
@@ -866,8 +852,9 @@ async def create_ad_creative(
     }
     
     # Choose between asset_feed_spec (dynamic creative) or object_story_spec (traditional)
-    if final_headlines or final_descriptions:
-        # Use asset_feed_spec for dynamic creatives
+    # ONLY use asset_feed_spec when user explicitly provides plural parameters (headlines/descriptions)
+    if headlines or descriptions:
+        # Use asset_feed_spec for dynamic creatives with multiple variants
         asset_feed_spec = {
             "ad_formats": ["SINGLE_IMAGE"],
             "images": [{"hash": image_hash}],
@@ -875,12 +862,12 @@ async def create_ad_creative(
         }
         
         # Handle headlines
-        if final_headlines:
-            asset_feed_spec["headlines"] = [{"text": headline_text} for headline_text in final_headlines]
+        if headlines:
+            asset_feed_spec["headlines"] = [{"text": headline_text} for headline_text in headlines]
             
         # Handle descriptions  
-        if final_descriptions:
-            asset_feed_spec["descriptions"] = [{"text": description_text} for description_text in final_descriptions]
+        if descriptions:
+            asset_feed_spec["descriptions"] = [{"text": description_text} for description_text in descriptions]
         
         # Add message as primary_texts if provided
         if message:
@@ -897,7 +884,7 @@ async def create_ad_creative(
             "page_id": page_id
         }
     else:
-        # Use traditional object_story_spec for single creative
+        # Use traditional object_story_spec with link_data for simple creatives
         creative_data["object_story_spec"] = {
             "page_id": page_id,
             "link_data": {
@@ -909,17 +896,25 @@ async def create_ad_creative(
         # Add optional parameters if provided
         if message:
             creative_data["object_story_spec"]["link_data"]["message"] = message
+        
+        # Add headline (singular) to link_data
+        if headline:
+            creative_data["object_story_spec"]["link_data"]["name"] = headline
+        
+        # Add description (singular) to link_data
+        if description:
+            creative_data["object_story_spec"]["link_data"]["description"] = description
+        
+        # Add call_to_action to link_data for simple creatives
+        if call_to_action_type:
+            creative_data["object_story_spec"]["link_data"]["call_to_action"] = {
+                "type": call_to_action_type
+            }
     
     # Add dynamic creative spec if provided
     if dynamic_creative_spec:
         creative_data["dynamic_creative_spec"] = dynamic_creative_spec
     
-    # Only add call_to_action to object_story_spec if we're not using asset_feed_spec
-    if call_to_action_type and "asset_feed_spec" not in creative_data:
-        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
     
@@ -998,32 +993,18 @@ async def update_ad_creative(
     if description and descriptions:
         return json.dumps({"error": "Cannot specify both 'description' and 'descriptions'. Use 'description' for single description or 'descriptions' for multiple."}, indent=2)
     
-    # Convert simple parameters to complex format for internal processing
-    final_headlines = None
-    final_descriptions = None
-    
-    if headline:
-        final_headlines = [headline]
-    elif headlines:
-        final_headlines = headlines
-        
-    if description:
-        final_descriptions = [description]
-    elif descriptions:
-        final_descriptions = descriptions
-    
-    # Validate dynamic creative parameters
-    if final_headlines:
-        if len(final_headlines) > 5:
+    # Validate dynamic creative parameters (plural forms only)
+    if headlines:
+        if len(headlines) > 5:
             return json.dumps({"error": "Maximum 5 headlines allowed for dynamic creatives"}, indent=2)
-        for i, h in enumerate(final_headlines):
+        for i, h in enumerate(headlines):
             if len(h) > 40:
                 return json.dumps({"error": f"Headline {i+1} exceeds 40 character limit"}, indent=2)
     
-    if final_descriptions:
-        if len(final_descriptions) > 5:
+    if descriptions:
+        if len(descriptions) > 5:
             return json.dumps({"error": "Maximum 5 descriptions allowed for dynamic creatives"}, indent=2)
-        for i, d in enumerate(final_descriptions):
+        for i, d in enumerate(descriptions):
             if len(d) > 125:
                 return json.dumps({"error": f"Description {i+1} exceeds 125 character limit"}, indent=2)
     
@@ -1033,45 +1014,58 @@ async def update_ad_creative(
     if name:
         update_data["name"] = name
     
-    if message:
-        update_data["object_story_spec"] = {"link_data": {"message": message}}
-    
-    # Handle dynamic creative assets via asset_feed_spec
-    if final_headlines or final_descriptions or dynamic_creative_spec:
+    # Choose between asset_feed_spec (dynamic creative) or object_story_spec (traditional)
+    # ONLY use asset_feed_spec when user explicitly provides plural parameters (headlines/descriptions)
+    if headlines or descriptions or dynamic_creative_spec:
+        # Handle dynamic creative assets via asset_feed_spec
         asset_feed_spec = {}
         
         # Add required ad_formats field for dynamic creatives
         asset_feed_spec["ad_formats"] = ["SINGLE_IMAGE"]
         
         # Handle headlines
-        if final_headlines:
-            asset_feed_spec["headlines"] = [{"text": headline_text} for headline_text in final_headlines]
+        if headlines:
+            asset_feed_spec["headlines"] = [{"text": headline_text} for headline_text in headlines]
             
         # Handle descriptions  
-        if final_descriptions:
-            asset_feed_spec["descriptions"] = [{"text": description_text} for description_text in final_descriptions]
+        if descriptions:
+            asset_feed_spec["descriptions"] = [{"text": description_text} for description_text in descriptions]
         
         # Add message as primary_texts if provided
         if message:
             asset_feed_spec["primary_texts"] = [{"text": message}]
         
+        # Add call_to_action_types if provided
+        if call_to_action_type:
+            asset_feed_spec["call_to_action_types"] = [call_to_action_type]
+        
         update_data["asset_feed_spec"] = asset_feed_spec
+    else:
+        # Use traditional object_story_spec with link_data for simple creatives
+        if message or headline or description or call_to_action_type:
+            update_data["object_story_spec"] = {"link_data": {}}
+            
+            if message:
+                update_data["object_story_spec"]["link_data"]["message"] = message
+            
+            # Add headline (singular) to link_data
+            if headline:
+                update_data["object_story_spec"]["link_data"]["name"] = headline
+            
+            # Add description (singular) to link_data
+            if description:
+                update_data["object_story_spec"]["link_data"]["description"] = description
+            
+            # Add call_to_action to link_data for simple creatives
+            if call_to_action_type:
+                update_data["object_story_spec"]["link_data"]["call_to_action"] = {
+                    "type": call_to_action_type
+                }
     
     # Add dynamic creative spec if provided
     if dynamic_creative_spec:
         update_data["dynamic_creative_spec"] = dynamic_creative_spec
     
-    # Handle call_to_action - add to asset_feed_spec if using dynamic creative, otherwise to object_story_spec
-    if call_to_action_type:
-        if "asset_feed_spec" in update_data:
-            update_data["asset_feed_spec"]["call_to_action_types"] = [call_to_action_type]
-        else:
-            if "object_story_spec" not in update_data:
-                update_data["object_story_spec"] = {"link_data": {}}
-            update_data["object_story_spec"]["link_data"]["call_to_action"] = {
-                "type": call_to_action_type
-            }
-    
     # Prepare the API endpoint for updating the creative
     endpoint = f"{creative_id}"
     

meta_ads_mcp/core/api.py

@@ -6,7 +6,8 @@ import httpx
 import asyncio
 import functools
 import os
-from .auth import needs_authentication, get_current_access_token, auth_manager, start_callback_server, shutdown_callback_server
+from . import auth
+from .auth import needs_authentication, auth_manager, start_callback_server, shutdown_callback_server
 from .utils import logger
 
 # Constants
@@ -203,7 +204,7 @@ def meta_api_tool(func):
             # If access_token is not in kwargs or not kwargs['access_token'], try to get it from auth_manager
             if 'access_token' not in kwargs or not kwargs['access_token']:
                 try:
-                    access_token = await get_current_access_token()
+                    access_token = await auth.get_current_access_token()
                     if access_token:
                         kwargs['access_token'] = access_token
                         logger.debug("Using access token from auth_manager")

meta_ads_mcp/core/authentication.py

@@ -29,7 +29,8 @@ from typing import Optional
 import asyncio
 import os
 from .api import meta_api_tool
-from .auth import start_callback_server, shutdown_callback_server, auth_manager, get_current_access_token
+from . import auth
+from .auth import start_callback_server, shutdown_callback_server, auth_manager
 from .server import mcp_server
 from .utils import logger, META_APP_SECRET
 from .pipeboard_auth import pipeboard_auth_manager

meta_ads_mcp/core/campaigns.py

@@ -9,7 +9,14 @@ from .server import mcp_server
 
 @mcp_server.tool()
 @meta_api_tool
-async def get_campaigns(account_id: str, access_token: Optional[str] = None, limit: int = 10, status_filter: str = "", after: str = "") -> str:
+async def get_campaigns(
+    account_id: str, 
+    access_token: Optional[str] = None, 
+    limit: int = 10, 
+    status_filter: str = "", 
+    objective_filter: Union[str, List[str]] = "", 
+    after: str = ""
+) -> str:
     """
     Get campaigns for a Meta Ads account with optional filtering.
     
@@ -26,6 +33,11 @@ async def get_campaigns(account_id: str, access_token: Optional[str] = None, lim
         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.
+        objective_filter: Filter by campaign objective(s). Can be a single objective string or a list of objectives.
+                         Valid objectives: 'OUTCOME_AWARENESS', 'OUTCOME_TRAFFIC', 'OUTCOME_ENGAGEMENT',
+                         'OUTCOME_LEADS', 'OUTCOME_SALES', 'OUTCOME_APP_PROMOTION'.
+                         Examples: 'OUTCOME_LEADS' or ['OUTCOME_LEADS', 'OUTCOME_SALES'].
+                         Leave empty for all objectives.
         after: Pagination cursor to get the next set of results
     """
     # Require explicit account_id
@@ -38,10 +50,32 @@ async def get_campaigns(account_id: str, access_token: Optional[str] = None, lim
         "limit": limit
     }
     
+    # Build filtering array for complex filtering
+    filters = []
+    
     if status_filter:
         # API expects an array, encode it as a JSON string
         params["effective_status"] = json.dumps([status_filter])
     
+    # Handle objective filtering - supports both single string and list of objectives
+    if objective_filter:
+        # Convert single string to list for consistent handling
+        objectives = [objective_filter] if isinstance(objective_filter, str) else objective_filter
+        
+        # Filter out empty strings
+        objectives = [obj for obj in objectives if obj]
+        
+        if objectives:
+            filters.append({
+                "field": "objective",
+                "operator": "IN",
+                "value": objectives
+            })
+    
+    # Add filtering parameter if we have filters
+    if filters:
+        params["filtering"] = json.dumps(filters)
+    
     if after:
         params["after"] = after
     

meta_ads_mcp/core/duplication.py

@@ -6,7 +6,7 @@ import httpx
 from typing import Optional, Dict, Any, List, Union
 from .server import mcp_server
 from .api import meta_api_tool
-from .auth import get_current_access_token
+from . import auth
 from .http_auth_integration import FastMCPAuthIntegration
 
 
@@ -204,7 +204,7 @@ async def _forward_duplication_request(resource_type: str, resource_id: str, acc
         
         # Use provided access_token parameter if no Facebook token found in context
         if not facebook_token:
-            facebook_token = access_token if access_token else await get_current_access_token()
+            facebook_token = access_token if access_token else await auth.get_current_access_token()
         
         # Validate we have both required tokens
         if not pipeboard_token:

{meta_ads_mcp-1.0.13.dist-info → meta_ads_mcp-1.0.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 1.0.13
+Version: 1.0.16
 Summary: Model Context Protocol (MCP) server 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
@@ -25,12 +25,14 @@ Description-Content-Type: text/markdown
 
 # Meta Ads MCP
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with Meta Ads API. This tool enables AI models to access, analyze, and manage Meta advertising campaigns through a standardized interface, allowing LLMs to retrieve performance data, visualize ad creatives, and provide strategic insights for Facebook, Instagram, and other Meta platforms.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with Meta Ads. Analyze, manage and optimize Meta advertising campaigns through an AI interface. Use an LLM to retrieve performance data, visualize ad creatives, and provide strategic insights for your ads on Facebook, Instagram, and other Meta platforms.
 
 > **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.
 
 [![Meta Ads MCP Server Demo](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)
 
+[![MCP Badge](https://lobehub.com/badge/mcp/nictuku-meta-ads-mcp)](https://lobehub.com/mcp/nictuku-meta-ads-mcp)
+
 mcp-name: co.pipeboard/meta-ads-mcp
 
 ## Community & Support
@@ -66,6 +68,16 @@ The fastest and most reliable way to get started is to **[🚀 Get started with
 
 That's it! You can now ask Claude to analyze your Meta ad campaigns, get performance insights, and manage your advertising.
 
+#### Advanced: Direct Token Authentication (Claude)
+
+For direct token-based authentication without the interactive flow, use this URL format when adding the integration:
+
+```
+https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN
+```
+
+Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
+
 ### For Cursor Users
 
 Add the following to your `~/.cursor/mcp.json`. Once you enable the remote MCP, click on "Needs login" to finish the login process.
@@ -81,12 +93,38 @@ Add the following to your `~/.cursor/mcp.json`. Once you enable the remote MCP,
 }
 ```
 
+#### Advanced: Direct Token Authentication (Cursor)
+
+If you prefer to authenticate without the interactive login flow, you can include your Pipeboard API token directly in the URL:
+
+```json
+{
+  "mcpServers": {
+    "meta-ads-remote": {
+      "url": "https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN"
+    }
+  }
+}
+```
+
+Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
+
 ### For Other MCP Clients
 
 Use the Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`
 
 **[📖 Get detailed setup instructions for your AI client here](https://pipeboard.co)**
 
+#### Advanced: Direct Token Authentication (Other Clients)
+
+For MCP clients that support token-based authentication, you can append your Pipeboard API token to the URL:
+
+```
+https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN
+```
+
+This bypasses the interactive login flow and authenticates immediately. Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
+
 ## Local Installation (Technical Users Only)
 
 If you're a developer or need to customize the installation, you can run Meta Ads MCP locally. **Most marketers should use the Remote MCP above instead!** For complete technical setup instructions, see our **[Local Installation Guide](LOCAL_INSTALLATION.md)**.

{meta_ads_mcp-1.0.13.dist-info → meta_ads_mcp-1.0.16.dist-info}/RECORD

@@ -1,17 +1,17 @@
-meta_ads_mcp/__init__.py,sha256=T0td-KBlHfj2ZrwXw6KM7u__flP25vlUMUyy5Befuzs,1477
+meta_ads_mcp/__init__.py,sha256=1vRTFKaJdcF1Ly2KZBp1Hp2QY-62dPdo5uEF1F4lsYo,1477
 meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
 meta_ads_mcp/core/__init__.py,sha256=IEJtqpyUo0CZSUWeQPljQ-D2vKorTFwXnpBQWSi1hIM,1819
 meta_ads_mcp/core/accounts.py,sha256=7Zoqq0zMIJi_Xsxe9-_b3EYx-UTeieJJvO7HxVRuUS0,4327
-meta_ads_mcp/core/ads.py,sha256=5ulQ4p3lLo1_sIiAoMdyeo0O2y7Yq2zSDuvqkNiqX1c,61376
+meta_ads_mcp/core/ads.py,sha256=s-E_ZzgbsMbnv2xblaDFgazcKDJIPyYKY8VC2dkeMBQ,61595
 meta_ads_mcp/core/ads_library.py,sha256=smGz9FhM6RIUjlQT4Jv1BaZmXahGdK21eRCB7QMhK-4,3228
 meta_ads_mcp/core/adsets.py,sha256=3Ok3EwPTReKshtsVs4gRMlws6LMTUJTb4ZeGPPM8JR8,16570
-meta_ads_mcp/core/api.py,sha256=dR1h3sTnSmIdEz8OSttqELA0YxBkbjMnSflgM5LsJ1A,16858
+meta_ads_mcp/core/api.py,sha256=RvEbXpVO_SxKJeuqsiQhpGYLZuhQlYKCd9hNv7AIZac,16856
 meta_ads_mcp/core/auth.py,sha256=l_IvejK2KYXg8yhBiP0ifE6mGwJ6ZujqYQbVw1KOUME,23649
-meta_ads_mcp/core/authentication.py,sha256=ftoKec1HpfYCCVYIVKUD3ezvVAk6n_CJlBuePn8fzpM,10547
+meta_ads_mcp/core/authentication.py,sha256=bAdmlSxQpqFN1vup9Wijl-iCfPLPMyFfMhIPdoNOPYg,10540
 meta_ads_mcp/core/budget_schedules.py,sha256=FVyJuKbjUE4cmtlPJEbIwpN6JmU-1WQjc7io1y5JaHE,2911
 meta_ads_mcp/core/callback_server.py,sha256=LIAJv9DW--83kdZ7VWWZal8xEprYjRZ8iug4rMczYbQ,9372
-meta_ads_mcp/core/campaigns.py,sha256=m24epO1QmyBVBXfqHIFZAi6sRCTlOGLQckjy0azqkvo,14319
-meta_ads_mcp/core/duplication.py,sha256=ae9GisFg9MMXbgX8zqb6ekEFIv7DGNCMV-lwkDXSL-c,18928
+meta_ads_mcp/core/campaigns.py,sha256=LKo5B8hNUUmfVQ1iu88o8HoU9ixOlGS9lwmPu6x9keA,15604
+meta_ads_mcp/core/duplication.py,sha256=pJ41pI9bIxNf21TSy6KkpcUsc3aSr4KIiO__sunNoq0,18909
 meta_ads_mcp/core/http_auth_integration.py,sha256=lGpKhfzJcyWugBcYEvypY-qnlt-3UDBLqh7xAUH0DGw,12473
 meta_ads_mcp/core/insights.py,sha256=ogSGlC0ddh8RFzWydilfDc7GYnjtInFiEQS7cSoyTmw,5061
 meta_ads_mcp/core/openai_deep_research.py,sha256=68ayGopnBSPEYhN9R1sFvTXtyWtM0lji9aWS3uSXnLY,18649
@@ -21,8 +21,8 @@ meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0
 meta_ads_mcp/core/server.py,sha256=9SlgM_qvdlxo24ctnZzLgW1e1nfAspCSx3YyJQkKP64,17856
 meta_ads_mcp/core/targeting.py,sha256=d2uLWbIEtucRuTgwZEdtVKLDZJgaxQ1lDtZ0ZgkBJC4,25150
 meta_ads_mcp/core/utils.py,sha256=ytj41yC5SqduLrAiZYBSd6OUwlJRaIClTwnnYKpNFds,9387
-meta_ads_mcp-1.0.13.dist-info/METADATA,sha256=W4fdNhV4K_RuA1d2Er-2Xqz46dHn0AJm-wDkLcL-DIk,24289
-meta_ads_mcp-1.0.13.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-1.0.13.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-1.0.13.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
-meta_ads_mcp-1.0.13.dist-info/RECORD,,
+meta_ads_mcp-1.0.16.dist-info/METADATA,sha256=N0dMtlXVrGmyFLgv3-IKS14giZL6JVXD_n9hjTZW3Os,25499
+meta_ads_mcp-1.0.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-1.0.16.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-1.0.16.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
+meta_ads_mcp-1.0.16.dist-info/RECORD,,