meta-ads-mcp 0.2.4__tar.gz → 0.2.5__tar.gz

{meta_ads_mcp-0.2.4 → meta_ads_mcp-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.2.4
+Version: 0.2.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
@@ -21,16 +21,26 @@ Description-Content-Type: text/markdown
 
 # Meta Ads MCP
 
-A [Model Calling Protocol (MCP)](https://github.com/anthropics/anthropic-tools) plugin for interacting with Meta Ads API.
+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.
+
+> **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.
+
+Screenhot: 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)
 
 ## Features
 
-- Seamless authentication with Meta's Graph API for desktop applications
-- Automatic token caching across sessions
-- Cross-platform support (Windows, macOS, Linux)
-- Access to ad accounts, campaigns, ad sets, and ads
-- Image download and analysis capabilities
-- Performance insights
+- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance
+- **Strategic Recommendations**: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content
+- **Automated Monitoring**: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes
+- **Budget Optimization**: Get recommendations for reallocating budget to better-performing ad sets
+- **Creative Improvement**: Receive feedback on ad copy, imagery, and calls-to-action
+- **Campaign Management**: Request changes to campaigns, ad sets, and ads (all changes require explicit confirmation)
+- **Cross-Platform Integration**: Works with Facebook, Instagram, and all Meta ad platforms
+- **Universal LLM Support**: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more
+- **Simple Authentication**: Easy setup with secure OAuth authentication
+- **Cross-Platform Support**: Works on Windows, macOS, and Linux
 
 ## Installation
 
@@ -39,7 +49,7 @@ A [Model Calling Protocol (MCP)](https://github.com/anthropics/anthropic-tools)
 When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
 
 ```bash
-uvx meta-ads-mcp
+uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
 ```
 
 If you want to install the package:
@@ -79,7 +89,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
 "mcpServers": {
   "meta-ads": {
     "command": "uvx",
-    "args": ["meta-ads-mcp"]
+    "args": ["meta-ads-mcp", "--app-id", "YOUR_META_ADS_APP_ID"]
   }
 }
 ```
@@ -350,4 +360,4 @@ You can check the current version of the package:
 ```python
 import meta_ads_mcp
 print(meta_ads_mcp.__version__)
-``` 
+``` 

{meta_ads_mcp-0.2.4 → meta_ads_mcp-0.2.5}/README.md

@@ -1,15 +1,25 @@
 # Meta Ads MCP
 
-A [Model Calling Protocol (MCP)](https://github.com/anthropics/anthropic-tools) plugin for interacting with Meta Ads API.
+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.
+
+> **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.
+
+Screenhot: 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)
 
 ## Features
 
-- Seamless authentication with Meta's Graph API for desktop applications
-- Automatic token caching across sessions
-- Cross-platform support (Windows, macOS, Linux)
-- Access to ad accounts, campaigns, ad sets, and ads
-- Image download and analysis capabilities
-- Performance insights
+- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance
+- **Strategic Recommendations**: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content
+- **Automated Monitoring**: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes
+- **Budget Optimization**: Get recommendations for reallocating budget to better-performing ad sets
+- **Creative Improvement**: Receive feedback on ad copy, imagery, and calls-to-action
+- **Campaign Management**: Request changes to campaigns, ad sets, and ads (all changes require explicit confirmation)
+- **Cross-Platform Integration**: Works with Facebook, Instagram, and all Meta ad platforms
+- **Universal LLM Support**: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more
+- **Simple Authentication**: Easy setup with secure OAuth authentication
+- **Cross-Platform Support**: Works on Windows, macOS, and Linux
 
 ## Installation
 
@@ -18,7 +28,7 @@ A [Model Calling Protocol (MCP)](https://github.com/anthropics/anthropic-tools)
 When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
 
 ```bash
-uvx meta-ads-mcp
+uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
 ```
 
 If you want to install the package:
@@ -58,7 +68,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
 "mcpServers": {
   "meta-ads": {
     "command": "uvx",
-    "args": ["meta-ads-mcp"]
+    "args": ["meta-ads-mcp", "--app-id", "YOUR_META_ADS_APP_ID"]
   }
 }
 ```
@@ -329,4 +339,4 @@ You can check the current version of the package:
 ```python
 import meta_ads_mcp
 print(meta_ads_mcp.__version__)
-``` 
+``` 

meta_ads_mcp-0.2.5/future_improvements.md

@@ -0,0 +1,11 @@
+# Future Improvements for Meta Ads MCP
+
+## Note about Meta Ads development work
+
+If you update the MCP server code, please note that *I* have to restart the MCP server. After the server code is changed, ask me to restart it and then proceed with your testing after I confirm it's restarted.
+
+## Access token should remain internal only
+
+Don't share it ever with the LLM, only update the auth cache.
+
+Future improvements can be added to this file as needed. 

{meta_ads_mcp-0.2.4 → meta_ads_mcp-0.2.5}/meta_ads_mcp/__init__.py

@@ -7,7 +7,7 @@ with the Claude LLM.
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 
 __all__ = [
     'get_ad_accounts',

{meta_ads_mcp-0.2.4 → meta_ads_mcp-0.2.5}/meta_ads_mcp/core/adsets.py

@@ -7,6 +7,7 @@ from .accounts import get_ad_accounts
 from .server import mcp_server
 import asyncio
 from .auth import start_callback_server, update_confirmation
+import urllib.parse
 
 
 @mcp_server.tool()
@@ -77,7 +78,7 @@ async def get_adset_details(access_token: str = None, adset_id: str = None) -> s
 @mcp_server.tool()
 @meta_api_tool
 async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, Any]] = None, bid_strategy: str = None, 
-                        bid_amount: int = None, status: str = None, access_token: str = None) -> str:
+                        bid_amount: int = None, status: str = None, targeting: Dict[str, Any] = None, access_token: str = None) -> str:
     """
     Update an ad set with new settings including frequency caps.
     
@@ -88,6 +89,8 @@ async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, An
         bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP')
         bid_amount: Bid amount in account currency (in cents for USD)
         status: Update ad set status (ACTIVE, PAUSED, etc.)
+        targeting: Targeting specifications including targeting_automation
+                  (e.g. {"targeting_automation":{"advantage_audience":1}})
         access_token: Meta API access token (optional - will use cached token if not provided)
     """
     if not adset_id:
@@ -106,6 +109,32 @@ async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, An
         
     if status is not None:
         changes['status'] = status
+        
+    if targeting is not None:
+        # Get current ad set details to preserve existing targeting settings
+        current_details_json = await get_adset_details(adset_id=adset_id, access_token=access_token)
+        current_details = json.loads(current_details_json)
+        
+        # Check if the current ad set has targeting information
+        current_targeting = current_details.get('targeting', {})
+        
+        if 'targeting_automation' in targeting:
+            # Only update targeting_automation while preserving other targeting settings
+            if current_targeting:
+                merged_targeting = current_targeting.copy()
+                merged_targeting['targeting_automation'] = targeting['targeting_automation']
+                changes['targeting'] = merged_targeting
+            else:
+                # If there's no existing targeting, we need to create a basic one
+                # Meta requires at least a geo_locations setting
+                basic_targeting = {
+                    'targeting_automation': targeting['targeting_automation'],
+                    'geo_locations': {'countries': ['US']}  # Using US as default location
+                }
+                changes['targeting'] = basic_targeting
+        else:
+            # Full targeting replacement
+            changes['targeting'] = targeting
     
     if not changes:
         return json.dumps({"error": "No update parameters provided"}, indent=2)
@@ -119,7 +148,8 @@ async def update_adset(adset_id: str, frequency_control_specs: List[Dict[str, An
     
     # Generate confirmation URL with properly encoded parameters
     changes_json = json.dumps(changes)
-    confirmation_url = f"http://localhost:{port}/confirm-update?adset_id={adset_id}&token={access_token}&changes={changes_json}"
+    encoded_changes = urllib.parse.quote(changes_json)
+    confirmation_url = f"http://localhost:{port}/confirm-update?adset_id={adset_id}&token={access_token}&changes={encoded_changes}"
     
     # Reset the update confirmation
     update_confirmation.clear()

{meta_ads_mcp-0.2.4 → meta_ads_mcp-0.2.5}/meta_ads_mcp/core/api.py

@@ -59,9 +59,9 @@ async def make_api_request(
     if not access_token:
         logger.error("API request attempted with blank access token")
         return {
-            "error": "Authentication Required",
-            "details": {
-                "message": "A valid access token is required to access the Meta API",
+            "error": {
+                "message": "Authentication Required",
+                "details": "A valid access token is required to access the Meta API",
                 "action_required": "Please authenticate first"
             }
         }
@@ -89,7 +89,18 @@ async def make_api_request(
             if method == "GET":
                 response = await client.get(url, params=request_params, headers=headers, timeout=30.0)
             elif method == "POST":
-                response = await client.post(url, json=request_params, headers=headers, timeout=30.0)
+                # For Meta API, POST requests need data, not JSON
+                if 'targeting' in request_params and isinstance(request_params['targeting'], dict):
+                    # Convert targeting dict to string for the API
+                    request_params['targeting'] = json.dumps(request_params['targeting'])
+                
+                # Convert lists and dicts to JSON strings    
+                for key, value in request_params.items():
+                    if isinstance(value, (list, dict)):
+                        request_params[key] = json.dumps(value)
+                
+                logger.debug(f"POST params (prepared): {masked_params}")
+                response = await client.post(url, data=request_params, headers=headers, timeout=30.0)
             elif method == "DELETE":
                 response = await client.delete(url, params=request_params, headers=headers, timeout=30.0)
             else:
@@ -97,7 +108,16 @@ async def make_api_request(
             
             response.raise_for_status()
             logger.debug(f"API Response status: {response.status_code}")
-            return response.json()
+            
+            # Ensure the response is JSON and return it as a dictionary
+            try:
+                return response.json()
+            except json.JSONDecodeError:
+                # If not JSON, return text content in a structured format
+                return {
+                    "text_response": response.text,
+                    "status_code": response.status_code
+                }
         
         except httpx.HTTPStatusError as e:
             error_info = {}
@@ -123,8 +143,7 @@ async def make_api_request(
                         logger.error(f"Current app_id: {app_id}")
                         # Provide a clearer error message without the confusing "Provide valid app ID" message
                         return {
-                            "error": f"HTTP Error: {e.response.status_code}",
-                            "details": {
+                            "error": {
                                 "message": "Meta API authentication configuration issue. Please check your app credentials.",
                                 "original_error": error_obj.get("message"),
                                 "code": error_obj.get("code")
@@ -132,11 +151,28 @@ async def make_api_request(
                         }
                     auth_manager.invalidate_token()
             
-            return {"error": f"HTTP Error: {e.response.status_code}", "details": error_info}
+            # Include full details for technical users
+            full_response = {
+                "headers": dict(e.response.headers),
+                "status_code": e.response.status_code,
+                "url": str(e.response.url),
+                "reason": getattr(e.response, "reason_phrase", "Unknown reason"),
+                "request_method": e.request.method,
+                "request_url": str(e.request.url)
+            }
+            
+            # Return a properly structured error object
+            return {
+                "error": {
+                    "message": f"HTTP Error: {e.response.status_code}",
+                    "details": error_info,
+                    "full_response": full_response
+                }
+            }
         
         except Exception as e:
             logger.error(f"Request Error: {str(e)}")
-            return {"error": str(e)}
+            return {"error": {"message": str(e)}}
 
 
 # Generic wrapper for all Meta API tools
@@ -174,12 +210,14 @@ def meta_api_tool(func):
                 logger.warning("No access token available, authentication needed")
                 auth_url = auth_manager.get_auth_url()
                 return json.dumps({
-                    "error": "Authentication Required",
-                    "details": {
-                        "message": "You need to authenticate with the Meta API before using this tool",
-                        "action_required": "Please authenticate first",
-                        "auth_url": auth_url,
-                        "markdown_link": f"[Click here to authenticate with Meta Ads API]({auth_url})"
+                    "error": {
+                        "message": "Authentication Required",
+                        "details": {
+                            "description": "You need to authenticate with the Meta API before using this tool",
+                            "action_required": "Please authenticate first",
+                            "auth_url": auth_url,
+                            "markdown_link": f"[Click here to authenticate with Meta Ads API]({auth_url})"
+                        }
                     }
                 }, indent=2)
                 
@@ -200,18 +238,24 @@ def meta_api_tool(func):
                                 logger.error(f"Current app_id: {app_id}")
                                 # Replace the confusing error with a more user-friendly one
                                 return json.dumps({
-                                    "error": "Meta API Configuration Issue",
-                                    "details": {
-                                        "message": "Your Meta API app is not properly configured",
-                                        "action_required": "Check your META_APP_ID environment variable",
-                                        "current_app_id": app_id,
-                                        "original_error": error_obj.get("message")
+                                    "error": {
+                                        "message": "Meta API Configuration Issue",
+                                        "details": {
+                                            "description": "Your Meta API app is not properly configured",
+                                            "action_required": "Check your META_APP_ID environment variable",
+                                            "current_app_id": app_id,
+                                            "original_error": error_obj.get("message")
+                                        }
                                     }
                                 }, indent=2)
                 except Exception:
-                    # Not JSON or other parsing error, just continue
-                    pass
-                
+                    # Not JSON or other parsing error, wrap it in a dictionary
+                    return json.dumps({"data": result}, indent=2)
+            
+            # If result is already a dictionary, ensure it's properly serialized
+            if isinstance(result, dict):
+                return json.dumps(result, indent=2)
+            
             return result
         except Exception as e:
             logger.error(f"Error in {func.__name__}: {str(e)}")