meta-ads-mcp 0.3.3__py3-none-any.whl → 0.3.6__py3-none-any.whl

meta_ads_mcp/__init__.py

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

meta_ads_mcp/api.py

@@ -841,7 +841,7 @@ async def create_campaign(
         access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
         name: Campaign name
-        objective: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
+        objective: Campaign objective. enum{BRAND_AWARENESS, LEAD_GENERATION, LINK_CLICKS, CONVERSIONS, OUTCOME_TRAFFIC, etc.}.
         status: Initial campaign status (default: PAUSED)
         special_ad_categories: List of special ad categories if applicable
         daily_budget: Daily budget in account currency (in cents)

meta_ads_mcp/core/__init__.py

@@ -10,6 +10,7 @@ from .authentication import get_login_link
 from .server import login_cli, main
 from .auth import login
 from .ads_library import search_ads_archive
+from .budget_schedules import create_budget_schedule
 
 __all__ = [
     'mcp_server',
@@ -33,4 +34,5 @@ __all__ = [
     'login',
     'main',
     'search_ads_archive',
+    'create_budget_schedule',
 ] 

meta_ads_mcp/core/budget_schedules.py

@@ -0,0 +1,71 @@
+"""Budget Schedule-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Dict, Any
+
+from .api import meta_api_tool, make_api_request
+from .server import mcp_server
+# Assuming no other specific dependencies from adsets.py are needed for this single function.
+# If other utilities from adsets.py (like get_ad_accounts) were needed, they'd be imported here.
+
+@mcp_server.tool()
+@meta_api_tool
+async def create_budget_schedule(
+    campaign_id: str,
+    budget_value: int,
+    budget_value_type: str,
+    time_start: int,
+    time_end: int,
+    access_token: str = None
+) -> str:
+    """
+    Create a budget schedule for a Meta Ads campaign.
+
+    Allows scheduling budget increases based on anticipated high-demand periods.
+    The times should be provided as Unix timestamps.
+    
+    Args:
+        campaign_id: Meta Ads campaign ID.
+        budget_value: Amount of budget increase. Interpreted based on budget_value_type.
+        budget_value_type: Type of budget value - "ABSOLUTE" or "MULTIPLIER".
+        time_start: Unix timestamp for when the high demand period should start.
+        time_end: Unix timestamp for when the high demand period should end.
+        access_token: Meta API access token (optional - will use cached token if not provided).
+        
+    Returns:
+        A JSON string containing the ID of the created budget schedule or an error message.
+    """
+    if not campaign_id:
+        return json.dumps({"error": "Campaign ID is required"}, indent=2)
+    if budget_value is None: # Check for None explicitly
+        return json.dumps({"error": "Budget value is required"}, indent=2)
+    if not budget_value_type:
+        return json.dumps({"error": "Budget value type is required"}, indent=2)
+    if budget_value_type not in ["ABSOLUTE", "MULTIPLIER"]:
+        return json.dumps({"error": "Invalid budget_value_type. Must be ABSOLUTE or MULTIPLIER"}, indent=2)
+    if time_start is None: # Check for None explicitly to allow 0
+        return json.dumps({"error": "Time start is required"}, indent=2)
+    if time_end is None: # Check for None explicitly to allow 0
+        return json.dumps({"error": "Time end is required"}, indent=2)
+
+    endpoint = f"{campaign_id}/budget_schedules"
+
+    params = {
+        "budget_value": budget_value,
+        "budget_value_type": budget_value_type,
+        "time_start": time_start,
+        "time_end": time_end,
+    }
+
+    try:
+        data = await make_api_request(endpoint, access_token, params, method="POST")
+        return json.dumps(data, indent=2)
+    except Exception as e:
+        error_msg = str(e)
+        # Include details about the error and the parameters sent for easier debugging
+        return json.dumps({
+            "error": "Failed to create budget schedule",
+            "details": error_msg,
+            "campaign_id": campaign_id,
+            "params_sent": params
+        }, indent=2) 

meta_ads_mcp/core/campaigns.py

@@ -104,7 +104,7 @@ async def create_campaign(
         access_token: Meta API access token (optional - will use cached token if not provided)
         account_id: Meta Ads account ID (format: act_XXXXXXXXX)
         name: Campaign name
-        objective: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
+        objective: Campaign objective. Validates ad objectives. enum{BRAND_AWARENESS, LEAD_GENERATION, LINK_CLICKS, CONVERSIONS, OUTCOME_TRAFFIC, etc.}.
         status: Initial campaign status (default: PAUSED)
         special_ad_categories: List of special ad categories if applicable
         daily_budget: Daily budget in account currency (in cents) as a string

{meta_ads_mcp-0.3.3.dist-info → meta_ads_mcp-0.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.3.3
+Version: 0.3.6
 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
@@ -11,7 +11,7 @@ Keywords: ads,api,claude,facebook,mcp,meta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.11
+Requires-Python: >=3.9.6
 Requires-Dist: httpx>=0.26.0
 Requires-Dist: mcp[cli]>=1.6.0
 Requires-Dist: pathlib>=1.0.1
@@ -27,11 +27,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 
 > **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.
 
-<a href="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp/badge" alt="Meta Ads MCP server" />
-</a>
-
-Screenshot: using an LLM to understand your ad performance.
+**Screenshot**: 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)
 
@@ -94,7 +90,7 @@ python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
 Before using the MCP server, you'll need to set up a Meta Developer App:
 
 1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
-2. Choose the "Consumer" app type
+2. Choose the "Business" app type
 3. In your app settings, add the "Marketing API" product
 4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
 5. Note your App ID (Client ID) for use with the MCP
@@ -181,38 +177,94 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
      - `adset_id`: Meta Ads ad set ID
    - Returns: Detailed information about the specified ad set
 
-9. `mcp_meta_ads_get_ads`
-   - Get ads for a Meta Ads account with optional filtering
+9. `mcp_meta_ads_create_adset`
+   - Create a new ad set in a Meta Ads account
    - Inputs:
-     - `access_token` (optional): Meta API access token (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
-   - Returns: List of ads matching the criteria
-
-10. `mcp_meta_ads_get_ad_details`
+     - `campaign_id`: Meta Ads campaign ID this ad set belongs to
+     - `name`: Ad set name
+     - `status`: Initial ad set status (default: PAUSED)
+     - `daily_budget`: Daily budget in account currency (in cents) as a string
+     - `lifetime_budget`: Lifetime budget in account currency (in cents) as a string
+     - `targeting`: Targeting specifications (e.g., age, location, interests)
+     - `optimization_goal`: Conversion optimization goal (e.g., 'LINK_CLICKS')
+     - `billing_event`: How you're charged (e.g., 'IMPRESSIONS')
+     - `bid_amount`: Bid amount in account currency (in cents)
+     - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST')
+     - `start_time`, `end_time`: Optional start/end times (ISO 8601)
+     - `access_token` (optional): Meta API access token
+   - Returns: Confirmation with new ad set details
+
+10. `mcp_meta_ads_get_ads`
+    - Get ads for a Meta Ads account with optional filtering
+    - Inputs:
+      - `access_token` (optional): Meta API access token (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
+    - Returns: List of ads matching the criteria
+
+11. `mcp_meta_ads_create_ad`
+    - Create a new ad with an existing creative
+    - Inputs:
+      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+      - `name`: Ad name
+      - `adset_id`: Ad set ID where this ad will be placed
+      - `creative_id`: ID of an existing creative to use
+      - `status`: Initial ad status (default: PAUSED)
+      - `bid_amount`: Optional bid amount (in cents)
+      - `tracking_specs`: Optional tracking specifications
+      - `access_token` (optional): Meta API access token
+    - Returns: Confirmation with new ad details
+
+12. `mcp_meta_ads_get_ad_details`
     - Get detailed information about a specific ad
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
       - `ad_id`: Meta Ads ad ID
     - Returns: Detailed information about the specified ad
 
-11. `mcp_meta_ads_get_ad_creatives`
+13. `mcp_meta_ads_get_ad_creatives`
     - Get creative details for a specific ad
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
       - `ad_id`: Meta Ads ad ID
     - Returns: Creative details including text, images, and URLs
 
-12. `mcp_meta_ads_get_ad_image`
+14. `mcp_meta_ads_create_ad_creative`
+    - Create a new ad creative using an uploaded image hash
+    - Inputs:
+      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+      - `name`: Creative name
+      - `image_hash`: Hash of the uploaded image
+      - `page_id`: Facebook Page ID for the ad
+      - `link_url`: Destination URL
+      - `message`: Ad copy/text
+      - `headline`: Ad headline
+      - `description`: Ad description
+      - `call_to_action_type`: CTA button type (e.g., 'LEARN_MORE')
+      - `instagram_actor_id`: Optional Instagram account ID
+      - `access_token` (optional): Meta API access token
+    - Returns: Confirmation with new creative details
+
+15. `mcp_meta_ads_upload_ad_image`
+    - Upload an image to use in Meta Ads creatives
+    - Inputs:
+      - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+      - `image_path`: Path to the image file to upload
+      - `name`: Optional name for the image
+      - `access_token` (optional): Meta API access token
+    - Returns: JSON response with image details including hash
+
+16. `mcp_meta_ads_get_ad_image`
     - Get, download, and visualize a Meta ad image in one step
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
       - `ad_id`: Meta Ads ad ID
     - Returns: The ad image ready for direct visual analysis
 
-13. `mcp_meta_ads_update_ad`
+17. `mcp_meta_ads_update_ad`
     - Update an ad with new settings
     - Inputs:
       - `ad_id`: Meta Ads ad ID
@@ -221,7 +273,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: Confirmation with updated ad details and a confirmation link
 
-14. `mcp_meta_ads_update_adset`
+18. `mcp_meta_ads_update_adset`
     - Update an ad set with new settings including frequency caps
     - Inputs:
       - `adset_id`: Meta Ads ad set ID
@@ -233,7 +285,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: Confirmation with updated ad set details and a confirmation link
 
-15. `mcp_meta_ads_get_insights`
+19. `mcp_meta_ads_get_insights`
     - Get performance insights for a campaign, ad set, ad or account
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -243,7 +295,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `level`: Level of aggregation (ad, adset, campaign, account)
     - Returns: Performance metrics for the specified object
 
-16. `mcp_meta_ads_debug_image_download`
+20. `mcp_meta_ads_debug_image_download`
     - Debug image download issues and report detailed diagnostics
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -251,12 +303,23 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
     - Returns: Diagnostic information about image download attempts
 
-17. `mcp_meta_ads_get_login_link`
+21. `mcp_meta_ads_get_login_link`
     - Get a clickable login link for Meta Ads authentication
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: A clickable resource link for Meta authentication
 
+22. `mcp_meta-ads_create_budget_schedule`
+    - Create a budget schedule for a Meta Ads campaign.
+    - Inputs:
+      - `campaign_id`: Meta Ads campaign ID.
+      - `budget_value`: Amount of budget increase.
+      - `budget_value_type`: Type of budget value ("ABSOLUTE" or "MULTIPLIER").
+      - `time_start`: Unix timestamp for when the high demand period should start.
+      - `time_end`: Unix timestamp for when the high demand period should end.
+      - `access_token` (optional): Meta API access token.
+    - Returns: JSON string with the ID of the created budget schedule or an error message.
+
 ## Authentication
 
 The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:

{meta_ads_mcp-0.3.3.dist-info → meta_ads_mcp-0.3.6.dist-info}/RECORD

@@ -1,7 +1,7 @@
-meta_ads_mcp/__init__.py,sha256=xQxyDpHFTg1FE9C3YEk88za2I8lvr8Mg0h9dMTxc5dw,1236
+meta_ads_mcp/__init__.py,sha256=HZ5-yaLTxk_DzYuRr0_vLonuqZfIVAOgzdB5gvspEcA,1236
 meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
-meta_ads_mcp/api.py,sha256=z0pW1pV3hE75IeG9QTqB3K7QoQOUxUg2MBQ9IjAWUYA,84363
-meta_ads_mcp/core/__init__.py,sha256=MOCvj3SkLvr5hFHqyjWOx7L4oReKLCoZaotwspJLwZQ,1022
+meta_ads_mcp/api.py,sha256=bQ7D1yNDMu7mRWLj8NBPT09azzrGgDjZVepZLxl4QjI,84414
+meta_ads_mcp/core/__init__.py,sha256=NvRA_socbKPEXFXIYdso5jBHb8cEEpF_2Mwhe3Obguw,1105
 meta_ads_mcp/core/accounts.py,sha256=Nmp7lPxO9wmq25jWV7_H0LIqnEbBhpCVBlLGW2HUaq0,2277
 meta_ads_mcp/core/ads.py,sha256=b_81GlGHIM4jISvuDZmHNyc6uW7uD3ovX68ezBci9MM,29747
 meta_ads_mcp/core/ads_library.py,sha256=onStn9UkRqYDC60gOPS-iKDtP1plz6DygUb7hUZ0Jw8,2807
@@ -9,15 +9,16 @@ meta_ads_mcp/core/adsets.py,sha256=WBPNaI7ITnUOnGMus4_0MX15DslOCzfM5q1zF1VWs2s,1
 meta_ads_mcp/core/api.py,sha256=9Whcs2orILhPiWkAR3qGmJNouYE5uri_e_Jzeh5Hjn8,14208
 meta_ads_mcp/core/auth.py,sha256=pDARBh3NBNqCpxflVrVvR4VsWuIveFxQmb9-P-gLFDM,20730
 meta_ads_mcp/core/authentication.py,sha256=2MG13r28OlIcOIgPSRrGXJ2-4JSt3ifU-oB9tiOsrKQ,6511
+meta_ads_mcp/core/budget_schedules.py,sha256=UxseExsvKAiPwfDCY9aycT4kys4xqeNytyq-yyDOxrs,2901
 meta_ads_mcp/core/callback_server.py,sha256=AUymElaVwHqFyqB2wgqf6A68KsqwtKoYmY-7JZZt8Ks,43286
-meta_ads_mcp/core/campaigns.py,sha256=TQHDhJ0s7cLbo5-zd2Bk8YgwToWBoK3YBMFG8fZbEHI,10757
+meta_ads_mcp/core/campaigns.py,sha256=H1ZQ9m2BkyxO7b6TPo6bOgBDGu0VCezXv-0BwmXFZ5E,10833
 meta_ads_mcp/core/insights.py,sha256=XAm4uu83gWp84PEGqAJ3GFIqlvg7prh6MdD71JfvBCo,18072
 meta_ads_mcp/core/pipeboard_auth.py,sha256=VvbxEB8ZOhnMccLU7HI1HgaPWHCl5NGrzZCm-zzHze4,22798
 meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
 meta_ads_mcp/core/server.py,sha256=5WofyJZGzeDhbGzLXPhQjT0XnZwo0syeK8TM_XnJo4Q,5507
 meta_ads_mcp/core/utils.py,sha256=EPmpBX3OZaTWRS_YuEk_PLLyLXj7DeR6Ks8WoaZ5JGQ,6366
-meta_ads_mcp-0.3.3.dist-info/METADATA,sha256=C1jgrXLiHpq2uRgTp259f2B639FevzezEextSF_xyUc,16611
-meta_ads_mcp-0.3.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.3.3.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.3.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-meta_ads_mcp-0.3.3.dist-info/RECORD,,
+meta_ads_mcp-0.3.6.dist-info/METADATA,sha256=1MN-vTf7bgXXajtstLqv0A_HvRLAY2QH7jmagwLgcx4,19650
+meta_ads_mcp-0.3.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.3.6.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.3.6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+meta_ads_mcp-0.3.6.dist-info/RECORD,,