meta-ads-mcp 0.2.8__tar.gz → 0.2.9__tar.gz

meta_ads_mcp-0.2.9/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

{meta_ads_mcp-0.2.8 → meta_ads_mcp-0.2.9}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.2.8
+Version: 0.2.9
 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
 Author-email: Your Name <your.email@example.com>
 License: MIT
+License-File: LICENSE
 Keywords: ads,api,claude,facebook,mcp,meta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -26,6 +27,10 @@ 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>
+
 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)
@@ -108,9 +113,9 @@ The easiest way to configure Meta Ads MCP is using Pipeboard authentication:
 
 This method provides longer-lived tokens (60 days), simplified setup, and automatic token renewal.
 
-### Usage with Claude in Cursor
+### Usage with Cursor or Claude Desktop
 
-Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor:
+Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cursor/mcp.json` to integrate with Cursor:
 
 ```json
 "mcpServers": {

{meta_ads_mcp-0.2.8 → meta_ads_mcp-0.2.9}/README.md

@@ -4,6 +4,10 @@ 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>
+
 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)
@@ -86,9 +90,9 @@ The easiest way to configure Meta Ads MCP is using Pipeboard authentication:
 
 This method provides longer-lived tokens (60 days), simplified setup, and automatic token renewal.
 
-### Usage with Claude in Cursor
+### Usage with Cursor or Claude Desktop
 
-Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor:
+Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cursor/mcp.json` to integrate with Cursor:
 
 ```json
 "mcpServers": {

{meta_ads_mcp-0.2.8 → meta_ads_mcp-0.2.9}/meta_ads_mcp/__init__.py

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

meta_ads_mcp-0.2.9/meta_ads_mcp/core/ads.py

@@ -0,0 +1,357 @@
+"""Ad and Creative-related functionality for Meta Ads API."""
+
+import json
+from typing import Optional, Dict, Any, List
+import io
+from PIL import Image as PILImage
+from mcp.server.fastmcp import Image
+
+from .api import meta_api_tool, make_api_request
+from .accounts import get_ad_accounts
+from .utils import download_image, try_multiple_download_methods, ad_creative_images
+from .server import mcp_server
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_ads(access_token: str = None, account_id: str = None, limit: int = 10, 
+                 campaign_id: str = "", adset_id: str = "") -> str:
+    """
+    Get ads for a Meta Ads account with optional filtering.
+    
+    Args:
+        access_token: Meta API access token (optional - 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
+    """
+    # If no account ID is specified, try to get the first one for the user
+    if not account_id:
+        accounts_json = await get_ad_accounts("me", json.dumps({"limit": 1}), access_token)
+        accounts_data = json.loads(accounts_json)
+        
+        if "data" in accounts_data and accounts_data["data"]:
+            account_id = accounts_data["data"][0]["id"]
+        else:
+            return json.dumps({"error": "No account ID specified and no accounts found for user"}, indent=2)
+    
+    # Use campaign-specific endpoint if campaign_id is provided
+    if campaign_id:
+        endpoint = f"{campaign_id}/ads"
+        params = {
+            "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
+            "limit": limit
+        }
+        # Adset ID can still be used to filter within the campaign
+        if adset_id:
+            params["adset_id"] = adset_id
+    else:
+        # Default to account-level endpoint if no campaign_id
+        endpoint = f"{account_id}/ads"
+        params = {
+            "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs",
+            "limit": limit
+        }
+        # Adset ID can filter at the account level if no campaign specified
+        if adset_id:
+            params["adset_id"] = adset_id
+
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_ad_details(access_token: str = None, ad_id: str = None) -> str:
+    """
+    Get detailed information about a specific ad.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+    """
+    if not ad_id:
+        return json.dumps({"error": "No ad ID provided"}, indent=2)
+        
+    endpoint = f"{ad_id}"
+    params = {
+        "fields": "id,name,adset_id,campaign_id,status,creative,created_time,updated_time,bid_amount,conversion_domain,tracking_specs,preview_shareable_link"
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def create_ad(
+    account_id: str = None,
+    name: str = None,
+    adset_id: str = None,
+    creative_id: str = None,
+    status: str = "PAUSED",
+    bid_amount = None,
+    tracking_specs: Optional[List[Dict[str, Any]]] = None,
+    access_token: str = None
+) -> str:
+    """
+    Create a new ad with an existing creative.
+    
+    Args:
+        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 account currency (in cents)
+        tracking_specs: Optional tracking specifications (e.g., for pixel events).
+                      Example: [{"action.type":"offsite_conversion","fb_pixel":["YOUR_PIXEL_ID"]}]
+        access_token: Meta API access token (optional - will use cached token if not provided)
+    """
+    # Check required parameters
+    if not account_id:
+        return json.dumps({"error": "No account ID provided"}, indent=2)
+    
+    if not name:
+        return json.dumps({"error": "No ad name provided"}, indent=2)
+    
+    if not adset_id:
+        return json.dumps({"error": "No ad set ID provided"}, indent=2)
+    
+    if not creative_id:
+        return json.dumps({"error": "No creative ID provided"}, indent=2)
+    
+    endpoint = f"{account_id}/ads"
+    
+    params = {
+        "name": name,
+        "adset_id": adset_id,
+        "creative": {"creative_id": creative_id},
+        "status": status
+    }
+    
+    # Add bid amount if provided
+    if bid_amount is not None:
+        params["bid_amount"] = str(bid_amount)
+        
+    # Add tracking specs if provided
+    if tracking_specs is not None:
+        params["tracking_specs"] = json.dumps(tracking_specs) # Needs to be JSON encoded string
+    
+    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)
+        return json.dumps({
+            "error": "Failed to create ad",
+            "details": error_msg,
+            "params_sent": params
+        }, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_ad_creatives(access_token: str = None, ad_id: str = None) -> str:
+    """
+    Get creative details for a specific ad. Best if combined with get_ad_image to get the full image.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+    """
+    if not ad_id:
+        return json.dumps({"error": "No ad ID provided"}, indent=2)
+        
+    endpoint = f"{ad_id}/adcreatives"
+    params = {
+        "fields": "id,name,status,thumbnail_url,image_url,image_hash,object_story_spec" # Added image_hash
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    # Add image URLs for direct viewing if available
+    if 'data' in data:
+        for creative in data['data']:
+            creative['image_urls_for_viewing'] = ad_creative_images(creative)
+
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_ad_image(access_token: str = None, ad_id: str = None) -> Image:
+    """
+    Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        ad_id: Meta Ads ad ID
+    
+    Returns:
+        The ad image ready for direct visual analysis
+    """
+    if not ad_id:
+        return "Error: No ad ID provided"
+        
+    print(f"Attempting to get and analyze creative image for ad {ad_id}")
+    
+    # First, get creative and account IDs
+    ad_endpoint = f"{ad_id}"
+    ad_params = {
+        "fields": "creative{id},account_id"
+    }
+    
+    ad_data = await make_api_request(ad_endpoint, access_token, ad_params)
+    
+    if "error" in ad_data:
+        return f"Error: Could not get ad data - {json.dumps(ad_data)}"
+    
+    # Extract account_id
+    account_id = ad_data.get("account_id", "")
+    if not account_id:
+        return "Error: No account ID found"
+    
+    # Extract creative ID
+    if "creative" not in ad_data:
+        return "Error: No creative found for this ad"
+        
+    creative_data = ad_data.get("creative", {})
+    creative_id = creative_data.get("id")
+    if not creative_id:
+        return "Error: No creative ID found"
+    
+    # Get creative details to find image hash
+    creative_endpoint = f"{creative_id}"
+    creative_params = {
+        "fields": "id,name,image_hash,asset_feed_spec"
+    }
+    
+    creative_details = await make_api_request(creative_endpoint, access_token, creative_params)
+    
+    # Identify image hashes to use from creative
+    image_hashes = []
+    
+    # Check for direct image_hash on creative
+    if "image_hash" in creative_details:
+        image_hashes.append(creative_details["image_hash"])
+    
+    # Check asset_feed_spec for image hashes - common in Advantage+ ads
+    if "asset_feed_spec" in creative_details and "images" in creative_details["asset_feed_spec"]:
+        for image in creative_details["asset_feed_spec"]["images"]:
+            if "hash" in image:
+                image_hashes.append(image["hash"])
+    
+    if not image_hashes:
+        # If no hashes found, try to extract from the first creative we found in the API
+        # Get creative for ad to try to extract hash
+        creative_json = await get_ad_creatives(ad_id, "", access_token)
+        creative_data = json.loads(creative_json)
+        
+        # Try to extract hash from asset_feed_spec
+        if "asset_feed_spec" in creative_data and "images" in creative_data["asset_feed_spec"]:
+            images = creative_data["asset_feed_spec"]["images"]
+            if images and len(images) > 0 and "hash" in images[0]:
+                image_hashes.append(images[0]["hash"])
+    
+    if not image_hashes:
+        return "Error: No image hashes found in creative"
+    
+    print(f"Found image hashes: {image_hashes}")
+    
+    # Now fetch image data using adimages endpoint with specific format
+    image_endpoint = f"act_{account_id}/adimages"
+    
+    # Format the hashes parameter exactly as in our successful curl test
+    hashes_str = f'["{image_hashes[0]}"]'  # Format first hash only, as JSON string array
+    
+    image_params = {
+        "fields": "hash,url,width,height,name,status",
+        "hashes": hashes_str
+    }
+    
+    print(f"Requesting image data with params: {image_params}")
+    image_data = await make_api_request(image_endpoint, access_token, image_params)
+    
+    if "error" in image_data:
+        return f"Error: Failed to get image data - {json.dumps(image_data)}"
+    
+    if "data" not in image_data or not image_data["data"]:
+        return "Error: No image data returned from API"
+    
+    # Get the first image URL
+    first_image = image_data["data"][0]
+    image_url = first_image.get("url")
+    
+    if not image_url:
+        return "Error: No valid image URL found"
+    
+    print(f"Downloading image from URL: {image_url}")
+    
+    # Download the image
+    image_bytes = await download_image(image_url)
+    
+    if not image_bytes:
+        return "Error: Failed to download image"
+    
+    try:
+        # Convert bytes to PIL Image
+        img = PILImage.open(io.BytesIO(image_bytes))
+        
+        # Convert to RGB if needed
+        if img.mode != "RGB":
+            img = img.convert("RGB")
+            
+        # Create a byte stream of the image data
+        byte_arr = io.BytesIO()
+        img.save(byte_arr, format="JPEG")
+        img_bytes = byte_arr.getvalue()
+        
+        # Return as an Image object that LLM can directly analyze
+        return Image(data=img_bytes, format="jpeg")
+        
+    except Exception as e:
+        return f"Error processing image: {str(e)}"
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def update_ad(
+    ad_id: str,
+    status: str = None,
+    bid_amount: int = None,
+    tracking_specs = None,
+    access_token: str = None
+) -> str:
+    """
+    Update an ad with new settings.
+    
+    Args:
+        ad_id: Meta Ads ad ID
+        status: Update ad status (ACTIVE, PAUSED, etc.)
+        bid_amount: Bid amount in account currency (in cents for USD)
+        tracking_specs: Optional tracking specifications (e.g., for pixel events).
+        access_token: Meta API access token (optional - will use cached token if not provided)
+    """
+    if not ad_id:
+        return json.dumps({"error": "Ad ID is required"}, indent=2)
+
+    params = {}
+    if status:
+        params["status"] = status
+    if bid_amount is not None:
+        # Ensure bid_amount is sent as a string if it's not null
+        params["bid_amount"] = str(bid_amount)
+    if tracking_specs is not None: # Add tracking_specs to params if provided
+        params["tracking_specs"] = json.dumps(tracking_specs) # Needs to be JSON encoded string
+
+    if not params:
+        return json.dumps({"error": "No update parameters provided (status, bid_amount, or tracking_specs)"}, indent=2)
+
+    endpoint = f"{ad_id}"
+    data = await make_api_request(endpoint, access_token, params, method='POST')
+
+    return json.dumps(data, indent=2)