meta-ads-mcp-python 1.0.79__py3-none-any.whl

meta_ads_mcp/__init__.py

@@ -0,0 +1,79 @@
+"""
+Meta Ads MCP - Python Package
+
+This package provides a Meta Ads MCP integration
+"""
+
+from meta_ads_mcp.core.server import main
+
+__version__ = "1.0.79"
+
+__all__ = [
+    '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',
+    'update_ad',
+    'get_insights',
+    # 'get_login_link' is conditionally exported via core.__all__
+    'login_cli',
+    'main',
+    'search_interests',
+    'get_interest_suggestions',
+    'estimate_audience_size',
+    'search_behaviors',
+    'search_demographics',
+    'search_geo_locations',
+    # MCC / Business Manager tools
+    'get_businesses',
+    'get_business_ad_accounts',
+    'find_client_account',
+    'get_business_details',
+]
+
+# Import key functions to make them available at package level
+from .core import (
+    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,
+    update_ad,
+    get_insights,
+    login_cli,
+    main,
+    search_interests,
+    get_interest_suggestions,
+    estimate_audience_size,
+    search_behaviors,
+    search_demographics,
+    search_geo_locations,
+    # MCC / Business Manager tools
+    get_businesses,
+    get_business_ad_accounts,
+    find_client_account,
+    get_business_details,
+)
+
+# 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() 
+
+# 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,55 @@
+"""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
+from .adsets import get_adsets, get_adset_details
+from .ads import get_ads, get_ad_details, get_creative_details, get_ad_creatives, get_ad_image
+from .insights import get_insights
+from . import authentication  # Import module to register conditional auth tools
+from .server import login_cli, main
+from .auth import login
+from . import ads_library  # Import module to register conditional tools
+from .targeting import search_interests, get_interest_suggestions, estimate_audience_size, search_behaviors, search_demographics, search_geo_locations
+from . import reports  # Import module to register conditional tools
+from . import duplication  # Import module to register conditional duplication tools
+from .openai_deep_research import search, fetch  # OpenAI MCP Deep Research tools
+from .mcc import (  # Business Manager (MCC) tools
+    get_businesses,
+    get_business_ad_accounts,
+    find_client_account,
+    get_business_details,
+)
+
+__all__ = [
+    'mcp_server',
+    'get_ad_accounts',
+    'get_account_info',
+    'get_campaigns',
+    'get_campaign_details',
+    'get_adsets',
+    'get_adset_details',
+    'get_ads',
+    'get_ad_details',
+    'get_creative_details',
+    'get_ad_creatives',
+    'get_ad_image',
+    'get_insights',
+    # Note: 'get_login_link' is registered conditionally by the authentication module
+    'login_cli',
+    'login',
+    'main',
+    'search_interests',
+    'get_interest_suggestions',
+    'estimate_audience_size',
+    'search_behaviors',
+    'search_demographics',
+    'search_geo_locations',
+    'search',  # OpenAI MCP Deep Research search tool
+    'fetch',   # OpenAI MCP Deep Research fetch tool
+    # MCC / Business Manager tools
+    'get_businesses',
+    'get_business_ad_accounts',
+    'find_client_account',
+    'get_business_details',
+] 

meta_ads_mcp/core/accounts.py

@@ -0,0 +1,141 @@
+"""Account-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Dict, Any
+from .api import meta_api_tool, make_api_request, ensure_act_prefix
+from .server import mcp_server
+
+# Currencies that have no sub-units (i.e., are not denominated in cents).
+# Meta API returns amount_spent and balance as integers in the smallest currency
+# unit, which is cents for most currencies but the base unit for these.
+_ZERO_DECIMAL_CURRENCIES = {
+    "BIF", "CLP", "DJF", "GNF", "JPY", "KMF", "KRW", "MGA",
+    "PYG", "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF",
+}
+
+
+def _cents_to_currency(amount, currency: str) -> str:
+    """Convert a Meta API monetary value (cents) to a currency-unit string.
+
+    Meta returns amount_spent and balance as integers representing the smallest
+    currency unit (cents for USD/EUR/GBP, base unit for zero-decimal currencies
+    like JPY). This converts to the human-readable decimal amount.
+    """
+    try:
+        amount_int = int(amount)
+    except (TypeError, ValueError):
+        return str(amount)
+    if currency.upper() in _ZERO_DECIMAL_CURRENCIES:
+        return str(amount_int)
+    return f"{amount_int / 100:.2f}"
+
+
+def _normalize_account_monetary_fields(account: dict) -> dict:
+    """Convert amount_spent and balance from cents to currency units in-place."""
+    currency = account.get("currency", "USD")
+    for field in ("amount_spent", "balance"):
+        if field in account:
+            account[field] = _cents_to_currency(account[field], currency)
+    return account
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_ad_accounts(access_token: Optional[str] = None, user_id: str = "me", limit: int = 200) -> str:
+    """
+    Get ad accounts accessible by a user.
+
+    amount_spent and balance are returned in currency units (e.g. USD dollars),
+    not cents.
+
+    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: 200)
+    """
+    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)
+
+    if "data" in data:
+        data["data"] = [_normalize_account_monetary_fields(acc) for acc in data["data"]]
+
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_account_info(account_id: str, access_token: Optional[str] = None) -> str:
+    """
+    Get detailed information about a specific ad account.
+    
+    Args:
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX)
+        access_token: Meta API access token (optional - will use cached token if not provided)
+    """
+    if not account_id:
+        return {
+            "error": {
+                "message": "Account ID is required",
+                "details": "Please specify an account_id parameter",
+                "example": "Use account_id='act_123456789' or account_id='123456789'"
+            }
+        }
+    
+    account_id = ensure_act_prefix(account_id)
+    
+    # Try to get the account info directly first
+    endpoint = f"{account_id}"
+    params = {
+        "fields": "id,name,account_id,account_status,amount_spent,balance,currency,age,business_city,business_country_code,timezone_name"
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+
+    # Check if the API request returned an error
+    if "error" in data:
+        # If access was denied, provide helpful error message with accessible accounts
+        if "access" in str(data.get("error", {})).lower() or "permission" in str(data.get("error", {})).lower():
+            # Get list of accessible accounts for helpful error message
+            accessible_endpoint = "me/adaccounts"
+            accessible_params = {
+                "fields": "id,name,account_id,account_status,amount_spent,balance,currency,age,business_city,business_country_code",
+                "limit": 50
+            }
+            accessible_accounts_data = await make_api_request(accessible_endpoint, access_token, accessible_params)
+            
+            if "data" in accessible_accounts_data:
+                accessible_accounts = [
+                    {"id": acc["id"], "name": acc["name"]} 
+                    for acc in accessible_accounts_data["data"][:10]  # Show first 10
+                ]
+                return {
+                    "error": {
+                        "message": f"Account {account_id} is not accessible to your user account",
+                        "details": "This account either doesn't exist or you don't have permission to access it",
+                        "accessible_accounts": accessible_accounts,
+                        "total_accessible_accounts": len(accessible_accounts_data["data"]),
+                        "suggestion": "Try using one of the accessible account IDs listed above"
+                    }
+                }
+        
+        # Return the original error for non-permission related issues
+        return data
+    
+    _normalize_account_monetary_fields(data)
+
+    # Add DSA requirement detection
+    if "business_country_code" in data:
+        european_countries = ["DE", "FR", "IT", "ES", "NL", "BE", "AT", "IE", "DK", "SE", "FI", "NO"]
+        if data["business_country_code"] in european_countries:
+            data["dsa_required"] = True
+            data["dsa_compliance_note"] = "This account is subject to European DSA (Digital Services Act) requirements"
+        else:
+            data["dsa_required"] = False
+            data["dsa_compliance_note"] = "This account is not subject to European DSA requirements"
+    
+    return data