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

meta_ads_mcp/core/ads.py

@@ -855,23 +855,25 @@ async def create_ad_creative(
     # 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
+        # Structure based on Meta API working example from documentation
+        # ad_formats must be specified with exactly one format
         asset_feed_spec = {
-            "ad_formats": ["SINGLE_IMAGE"],
             "images": [{"hash": image_hash}],
-            "link_urls": [{"website_url": link_url if link_url else "https://facebook.com"}]
+            "link_urls": [{"website_url": link_url if link_url else "https://facebook.com"}],
+            "ad_formats": ["SINGLE_IMAGE"]
         }
         
-        # Handle headlines
+        # Handle headlines - Meta API uses "titles" not "headlines" in asset_feed_spec
         if headlines:
-            asset_feed_spec["headlines"] = [{"text": headline_text} for headline_text in headlines]
+            asset_feed_spec["titles"] = [{"text": headline_text} for headline_text in headlines]
             
         # Handle descriptions  
         if descriptions:
             asset_feed_spec["descriptions"] = [{"text": description_text} for description_text in descriptions]
         
-        # Add message as primary_texts if provided
+        # Add message as bodies - Meta API uses "bodies" not "primary_texts" in asset_feed_spec
         if message:
-            asset_feed_spec["primary_texts"] = [{"text": message}]
+            asset_feed_spec["bodies"] = [{"text": message}]
         
         # Add call_to_action_types if provided
         if call_to_action_type:
@@ -879,7 +881,8 @@ async def create_ad_creative(
         
         creative_data["asset_feed_spec"] = asset_feed_spec
         
-        # For dynamic creatives, we need a simplified object_story_spec
+        # For dynamic creatives with asset_feed_spec, object_story_spec only needs page_id
+        # Link information is already in asset_feed_spec.link_urls
         creative_data["object_story_spec"] = {
             "page_id": page_id
         }
@@ -1023,17 +1026,17 @@ async def update_ad_creative(
         # Add required ad_formats field for dynamic creatives
         asset_feed_spec["ad_formats"] = ["SINGLE_IMAGE"]
         
-        # Handle headlines
+        # Handle headlines - Meta API uses "titles" not "headlines" in asset_feed_spec
         if headlines:
-            asset_feed_spec["headlines"] = [{"text": headline_text} for headline_text in headlines]
+            asset_feed_spec["titles"] = [{"text": headline_text} for headline_text in headlines]
             
         # Handle descriptions  
         if descriptions:
             asset_feed_spec["descriptions"] = [{"text": description_text} for description_text in descriptions]
         
-        # Add message as primary_texts if provided
+        # Add message as bodies - Meta API uses "bodies" not "primary_texts" in asset_feed_spec
         if message:
-            asset_feed_spec["primary_texts"] = [{"text": message}]
+            asset_feed_spec["bodies"] = [{"text": message}]
         
         # Add call_to_action_types if provided
         if call_to_action_type:

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-1.0.15.dist-info → meta_ads_mcp-1.0.18.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 1.0.15
-Summary: Model Context Protocol (MCP) server for interacting with Meta Ads API
+Version: 1.0.18
+Summary: Model Context Protocol (MCP) server for Meta Ads - Use Remote MCP at pipeboard.co for easiest setup
 Project-URL: Homepage, https://github.com/pipeboard-co/meta-ads-mcp
 Project-URL: Bug Tracker, https://github.com/pipeboard-co/meta-ads-mcp/issues
 Author-email: Yves Junqueira <yves.junqueira@gmail.com>
@@ -68,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.
@@ -83,31 +93,43 @@ 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)**
 
-## Local Installation (Technical Users Only)
+#### Advanced: Direct Token Authentication (Other Clients)
 
-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)**.
+For MCP clients that support token-based authentication, you can append your Pipeboard API token to the URL:
 
-Meta Ads MCP also supports **streamable HTTP transport**, allowing you to run it as a standalone HTTP API for web applications and custom integrations. See **[Streamable HTTP Setup Guide](STREAMABLE_HTTP_SETUP.md)** for complete instructions.
+```
+https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN
+```
 
-### Quick Local Setup
+This bypasses the interactive login flow and authenticates immediately. Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
 
-```bash
-# Install via uvx (recommended)
-uvx meta-ads-mcp
+## Local Installation (Advanced Technical Users Only)
 
-# Set your Pipeboard token
-export PIPEBOARD_API_TOKEN=your_pipeboard_token
+🚀 **We strongly recommend using [Remote MCP](https://pipeboard.co) instead** - it's faster, more reliable, and requires no technical setup.
 
-# Add to your MCP client configuration
-```
-
-For detailed step-by-step instructions, authentication setup, debugging, and troubleshooting, visit **[LOCAL_INSTALLATION.md](LOCAL_INSTALLATION.md)**.
+Meta Ads MCP also supports a local streamable HTTP transport, allowing you to run it as a standalone HTTP API for web applications and custom integrations. See **[Streamable HTTP Setup Guide](STREAMABLE_HTTP_SETUP.md)** for complete instructions.
 
 ## Features
 
@@ -130,9 +152,9 @@ For detailed step-by-step instructions, authentication setup, debugging, and tro
 
 **[✨ Get started with Remote MCP here](https://pipeboard.co)** - no technical setup required! Just connect your Facebook Ads account and start asking AI to analyze your campaigns.
 
-### Local Installation (Technical Users)
+### Local Installation (Advanced Technical Users)
 
-For local installation configuration, authentication options, and advanced technical setup, see our **[Local Installation Guide](LOCAL_INSTALLATION.md)**.
+For advanced users who need to self-host, the package can be installed from source. Local installations require creating your own Meta Developer App. **We recommend using [Remote MCP](https://pipeboard.co) for a simpler experience.**
 
 ### Available MCP Tools
 
@@ -458,7 +480,7 @@ The only restriction is that you cannot offer this as a competing hosted service
 Meta Ads MCP follows security best practices with secure token management and automatic authentication handling. 
 
 - **Remote MCP**: All authentication is handled securely in the cloud - no local token storage required
-- **Local Installation**: Tokens are cached securely on your local machine - see [Local Installation Guide](LOCAL_INSTALLATION.md) for details
+- **Local Installation**: Tokens are cached securely on your local machine
 
 ## Testing
 
@@ -470,7 +492,7 @@ Test your Meta Ads MCP connection with any MCP client:
 2. **Check Account Details**: Use `mcp_meta_ads_get_account_info` with your account ID
 3. **List Campaigns**: Try `mcp_meta_ads_get_campaigns` to see your ad campaigns
 
-For detailed local installation testing, see [Local Installation Guide](LOCAL_INSTALLATION.md).
+For detailed local installation testing, see the source repository.
 
 ## Troubleshooting
 
@@ -480,10 +502,4 @@ The easiest way to avoid any setup issues is to **[🎯 use our Remote MCP inste
 
 ### Local Installation Issues
 
-For comprehensive troubleshooting, debugging, and local installation issues, see our **[Local Installation Guide](LOCAL_INSTALLATION.md)** which includes:
-
-- Authentication troubleshooting
-- Installation issues and solutions
-- API error resolution
-- Debug logs and diagnostic commands
-- Performance optimization tips
+For local installation issues, refer to the source repository. **For the easiest experience, we recommend using [Remote MCP](https://pipeboard.co) instead.**

{meta_ads_mcp-1.0.15.dist-info → meta_ads_mcp-1.0.18.dist-info}/RECORD

@@ -1,8 +1,8 @@
-meta_ads_mcp/__init__.py,sha256=CZF19i71cp1oW8UN66DGURoUuqAlgTmIkQBISUiNovY,1477
+meta_ads_mcp/__init__.py,sha256=qVIccqA3rZtJUEMjPcFLKFUhyRlnAJyTyP4l29VklAU,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=s-E_ZzgbsMbnv2xblaDFgazcKDJIPyYKY8VC2dkeMBQ,61595
+meta_ads_mcp/core/ads.py,sha256=ED67n5kCcmqk5BDDTOA4zVYUPUsAJw8ZvlM2kVwNQlI,62007
 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=RvEbXpVO_SxKJeuqsiQhpGYLZuhQlYKCd9hNv7AIZac,16856
@@ -10,7 +10,7 @@ meta_ads_mcp/core/auth.py,sha256=l_IvejK2KYXg8yhBiP0ifE6mGwJ6ZujqYQbVw1KOUME,236
 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/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
@@ -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.15.dist-info/METADATA,sha256=cZhvlDIsRWU3a0JDj_HkV3oWa079qBrvcOmoC9RPZGw,24369
-meta_ads_mcp-1.0.15.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-1.0.15.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-1.0.15.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
-meta_ads_mcp-1.0.15.dist-info/RECORD,,
+meta_ads_mcp-1.0.18.dist-info/METADATA,sha256=9Dyns9X9nMyMP-ZCMWpFuk6lckX7ApqIAJIfIiYY_vs,24903
+meta_ads_mcp-1.0.18.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+meta_ads_mcp-1.0.18.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-1.0.18.dist-info/licenses/LICENSE,sha256=E2d762fbhwKRYn8o7J6Szr6vyBPrHVDlK3jbHPx-d84,3851
+meta_ads_mcp-1.0.18.dist-info/RECORD,,

{meta_ads_mcp-1.0.15.dist-info → meta_ads_mcp-1.0.18.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any