meta-ads-mcp 0.2.4__py3-none-any.whl → 0.2.6__py3-none-any.whl

meta_ads_mcp/core/utils.py

@@ -13,6 +13,16 @@ import logging
 import pathlib
 import platform
 
+# Check for Meta app credentials in environment
+META_APP_ID = os.environ.get("META_APP_ID", "")
+META_APP_SECRET = os.environ.get("META_APP_SECRET", "")
+
+# Print warning if Meta app credentials are not configured
+if not META_APP_ID:
+    print("WARNING: META_APP_ID environment variable is not set. Authentication will not work properly.")
+if not META_APP_SECRET:
+    print("WARNING: META_APP_SECRET environment variable is not set. Long-lived token exchange will not work.")
+
 # Configure logging to file
 def setup_logging():
     """Set up logging to file for troubleshooting."""

{meta_ads_mcp-0.2.4.dist-info → meta_ads_mcp-0.2.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.2.4
+Version: 0.2.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
@@ -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"]
   }
 }
 ```
@@ -177,7 +187,28 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `ad_id`: Meta Ads ad ID
     - Returns: The ad image ready for direct visual analysis
 
-12. `mcp_meta_ads_get_insights`
+12. `mcp_meta_ads_update_ad`
+    - Update an ad with new settings
+    - Inputs:
+      - `ad_id`: Meta Ads ad ID
+      - `status`: Update ad status (ACTIVE, PAUSED, etc.)
+      - `bid_amount`: Bid amount in account currency (in cents for USD)
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+    - Returns: Confirmation with updated ad details and a confirmation link
+
+13. `mcp_meta_ads_update_adset`
+    - Update an ad set with new settings including frequency caps
+    - Inputs:
+      - `adset_id`: Meta Ads ad set ID
+      - `frequency_control_specs`: List of frequency control specifications
+      - `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
+      - `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
+
+14. `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)
@@ -187,7 +218,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `level`: Level of aggregation (ad, adset, campaign, account)
     - Returns: Performance metrics for the specified object
 
-13. `mcp_meta_ads_debug_image_download`
+15. `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)
@@ -195,7 +226,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
       - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
     - Returns: Diagnostic information about image download attempts
 
-14. `mcp_meta_ads_get_login_link`
+16. `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)
@@ -350,4 +381,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.6.dist-info/RECORD

@@ -0,0 +1,20 @@
+meta_ads_mcp/__init__.py,sha256=r_A2NaKWasOAmt5IT2zhGrE2FRjVIMYiQKXZ9LMxTI0,1236
+meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
+meta_ads_mcp/api.py,sha256=9mmoJIdkC3PexZn3hw8XiKznecsbOSnhHtdEsJiPIyw,77475
+meta_ads_mcp/core/__init__.py,sha256=BA93zC6D8CzKbLo4JqqNqahq2LVgWBsoIXmJCK4AdIc,924
+meta_ads_mcp/core/accounts.py,sha256=Nmp7lPxO9wmq25jWV7_H0LIqnEbBhpCVBlLGW2HUaq0,2277
+meta_ads_mcp/core/ads.py,sha256=jAwa1gD3HpXFhDW53cUMYwnt52jmBjTHTwb9HUk0EaA,16975
+meta_ads_mcp/core/adsets.py,sha256=zSC67UhrhiinLY_SYSMNjRlmSZxCvyBYXIXroPBaVNc,7359
+meta_ads_mcp/core/api.py,sha256=AurfnoUZoIq9WS4cnsmVqpxc3pdsws8jvNhzQzdzLGg,12209
+meta_ads_mcp/core/auth.py,sha256=2uFGSD_6l8ExS1CQx7VQnPDq2yIb1fAk_t1BFFGQr7A,16881
+meta_ads_mcp/core/authentication.py,sha256=6zoGorswj5kRbrt_18A8KrZdCORNLGHybvb7XRQ1yJg,3474
+meta_ads_mcp/core/callback_server.py,sha256=b5TzUz9nEk0i5MWujlls5gAsHru__UjTPJQan1xQ_10,40947
+meta_ads_mcp/core/campaigns.py,sha256=u5jNHSxcWlZgzVLNmaeoovA9OcPjSUjTegUMcDLAurs,4381
+meta_ads_mcp/core/insights.py,sha256=f4Rs3kG0oqpKl8zBc_nt_zE0z4zvb9i0g12galrDiw8,17376
+meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
+meta_ads_mcp/core/server.py,sha256=-tClGe4rc-8U2ihgpipLstiTPRg3-CnjsTRgncsNa_A,3055
+meta_ads_mcp/core/utils.py,sha256=wxh722z-x0TSJwDEEeDylkv4VJqLmqnkZy-YGRzs4vQ,6049
+meta_ads_mcp-0.2.6.dist-info/METADATA,sha256=4UUxhxKMIfZ9bvMfqW6CJb8-6bJibUaXElSsdmrFBa4,15300
+meta_ads_mcp-0.2.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.2.6.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.2.6.dist-info/RECORD,,

meta_ads_mcp-0.2.4.dist-info/RECORD

@@ -1,19 +0,0 @@
-meta_ads_mcp/__init__.py,sha256=xmCT88Y60ifMx7uGEKOJBAF0JC1buzGdGexT9svhDtU,1204
-meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
-meta_ads_mcp/api.py,sha256=9mmoJIdkC3PexZn3hw8XiKznecsbOSnhHtdEsJiPIyw,77475
-meta_ads_mcp/core/__init__.py,sha256=BA93zC6D8CzKbLo4JqqNqahq2LVgWBsoIXmJCK4AdIc,924
-meta_ads_mcp/core/accounts.py,sha256=Nmp7lPxO9wmq25jWV7_H0LIqnEbBhpCVBlLGW2HUaq0,2277
-meta_ads_mcp/core/ads.py,sha256=TS37bUX8kJeeX4M2jv3StZev7Riq-n8Fm0TOhEL0eIY,14625
-meta_ads_mcp/core/adsets.py,sha256=Wuk5EJywypFNbPgdLGJ13XK7O6v7TyfwdR4f1MObGzE,5739
-meta_ads_mcp/core/api.py,sha256=vmMgX6pb4HkoLw3PXNekqrZCN4k06oZPtMF4128Wzz0,10133
-meta_ads_mcp/core/auth.py,sha256=2F1v3kWfl83NC8X_IyH-JUu0pQYtxplKZ-G5KyWSVAw,37222
-meta_ads_mcp/core/authentication.py,sha256=_lEi5XerkitD96jr6J8H9pUa1z1sp8SLr8iXvyr8fIg,2798
-meta_ads_mcp/core/campaigns.py,sha256=u5jNHSxcWlZgzVLNmaeoovA9OcPjSUjTegUMcDLAurs,4381
-meta_ads_mcp/core/insights.py,sha256=f4Rs3kG0oqpKl8zBc_nt_zE0z4zvb9i0g12galrDiw8,17376
-meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
-meta_ads_mcp/core/server.py,sha256=-tClGe4rc-8U2ihgpipLstiTPRg3-CnjsTRgncsNa_A,3055
-meta_ads_mcp/core/utils.py,sha256=ByVAoMoTlkAe2xtC2NRm9oqHrHiarsipXeWh0NZB2Xs,5574
-meta_ads_mcp-0.2.4.dist-info/METADATA,sha256=5iT4VVpfdDReyxWKsE8ITIXkZdu4XvBvAq_UJs_z46U,12507
-meta_ads_mcp-0.2.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.2.4.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
-meta_ads_mcp-0.2.4.dist-info/RECORD,,