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

meta_ads_mcp-0.2.5/META_API_NOTES.md

@@ -0,0 +1,28 @@
+# Meta Ads API Notes and Limitations
+
+## Frequency Cap Visibility
+The Meta Marketing API has some limitations regarding frequency cap visibility:
+
+1. **Optimization Goal Dependency**: Frequency cap settings (`frequency_control_specs`) are only visible in API responses for ad sets where the optimization goal is set to REACH. For other optimization goals (like LINK_CLICKS, CONVERSIONS, etc.), the frequency caps will still work but won't be visible through the API.
+
+2. **Verifying Frequency Caps**: Since frequency caps may not be directly visible, you can verify they're working by monitoring:
+   - The frequency metric in ad insights
+   - The ratio between reach and impressions over time
+   - The actual frequency cap behavior in the Meta Ads Manager UI
+
+## Other API Behaviors to Note
+
+1. **Field Visibility**: Some fields may not appear in API responses even when explicitly requested. This doesn't necessarily mean the field isn't set - it may just not be visible through the API.
+
+2. **Response Filtering**: The API may filter out empty or default values from responses to reduce payload size. If a field is missing from a response, it might mean:
+   - The field is not set
+   - The field has a default value
+   - The field is not applicable for the current configuration
+
+3. **Best Practices**:
+   - Always verify important changes through both the API and Meta Ads Manager UI
+   - Use insights and metrics to confirm behavioral changes when direct field access is limited
+   - Consider the optimization goal when setting up features like frequency caps
+
+## Updates and Changes
+Meta frequently updates their API behavior. These notes will be updated as we discover new limitations or changes in the API's behavior. 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.2.3
+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"]
   }
 }
 ```
@@ -195,14 +205,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_save_ad_image_via_api`
-    - Try to save an ad image by using the Marketing API's attachment endpoints
-    - Inputs:
-      - `access_token` (optional): Meta API access token (will use cached token if not provided)
-      - `ad_id`: Meta Ads ad ID
-    - Returns: Results of attempts to save the ad image
-
-15. `mcp_meta_ads_get_login_link`
+14. `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)
@@ -227,42 +230,73 @@ The Meta Ads MCP uses the OAuth 2.0 flow designed for desktop apps. When authent
 3. Ask you to authorize the app
 4. Redirect back to the local server to extract and store the token securely
 
-### Authentication Methods
+## Troubleshooting and Logging
+
+The Meta Ads MCP includes a comprehensive logging system to help troubleshoot issues:
+
+### Log Location
+
+Log files are stored in a platform-specific location:
+
+- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`
+- **Windows**: `%APPDATA%\meta-ads-mcp\meta_ads_debug.log` 
+- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log`
 
-There are two ways to authenticate with the Meta Ads API:
+### Common Issues
 
-1. **LLM/MCP Interface Authentication** (Recommended)
-   
-   When using the Meta Ads MCP through an LLM interface (like Claude), simply use any Meta Ads function. If you're not authenticated, the system will automatically provide a clickable Markdown link to complete the authentication flow.
+#### App ID Issues
 
-   ```
-   [Click here to authenticate with Meta Ads API](https://www.facebook.com/dialog/oauth?...)
-   ```
+If you encounter errors like `(#200) Provide valid app ID`, check the following:
 
-   Just click the link, complete the authorization in your browser, and the token will be automatically captured and stored.
+1. Ensure you've set up a Meta Developer App correctly
+2. Verify that you're passing the correct App ID using one of these methods:
+   - Set the `META_APP_ID` environment variable: `export META_APP_ID=your_app_id`
+   - Pass it as a command-line argument: `meta-ads-mcp --app-id your_app_id`
 
-2. **Command Line Authentication**
+#### Authentication Errors
 
-   You can authenticate directly from the command line:
+Authentication errors can be tracked in the log file. Check for:
+- Token expiration issues
+- App permission problems
+- Connection errors
 
-   ```bash
-   uvx meta-ads-mcp --login --app-id YOUR_APP_ID
-   ```
+### Debugging Command
 
-### Token Caching
+For specific image download issues, use the built-in diagnostic tool:
+
+```python
+# Using direct tool call
+mcp_meta_ads_debug_image_download(ad_id="your_ad_id")
+```
+
+This will give you detailed information about the download process and potential issues.
+
+## Running with Different App IDs
+
+If you need to use different Meta App IDs for different purposes:
+
+```bash
+# Using environment variable
+export META_APP_ID=your_app_id
+uvx meta-ads-mcp
+
+# Or using command line argument
+uvx meta-ads-mcp --app-id=your_app_id
+```
 
-Tokens are cached in a platform-specific secure location:
-- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
-- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
-- Linux: `~/.config/meta-ads-mcp/token_cache.json`
+## Privacy and Security
 
-You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
+The Meta Ads MCP follows security best practices:
 
-## Environment Variables
+1. Tokens are cached in a platform-specific secure location:
+   - Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
+   - macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
+   - Linux: `~/.config/meta-ads-mcp/token_cache.json`
 
-You can set the following environment variables instead of passing them as arguments:
+2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
 
-- `META_APP_ID`: Your Meta App ID (Client ID)
+3. You can set the following environment variables instead of passing them as arguments:
+   - `META_APP_ID`: Your Meta App ID (Client ID)
 
 ## Testing
 
@@ -326,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.3 → 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"]
   }
 }
 ```
@@ -174,14 +184,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_save_ad_image_via_api`
-    - Try to save an ad image by using the Marketing API's attachment endpoints
-    - Inputs:
-      - `access_token` (optional): Meta API access token (will use cached token if not provided)
-      - `ad_id`: Meta Ads ad ID
-    - Returns: Results of attempts to save the ad image
-
-15. `mcp_meta_ads_get_login_link`
+14. `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)
@@ -206,42 +209,73 @@ The Meta Ads MCP uses the OAuth 2.0 flow designed for desktop apps. When authent
 3. Ask you to authorize the app
 4. Redirect back to the local server to extract and store the token securely
 
-### Authentication Methods
+## Troubleshooting and Logging
+
+The Meta Ads MCP includes a comprehensive logging system to help troubleshoot issues:
+
+### Log Location
+
+Log files are stored in a platform-specific location:
+
+- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`
+- **Windows**: `%APPDATA%\meta-ads-mcp\meta_ads_debug.log` 
+- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log`
 
-There are two ways to authenticate with the Meta Ads API:
+### Common Issues
 
-1. **LLM/MCP Interface Authentication** (Recommended)
-   
-   When using the Meta Ads MCP through an LLM interface (like Claude), simply use any Meta Ads function. If you're not authenticated, the system will automatically provide a clickable Markdown link to complete the authentication flow.
+#### App ID Issues
 
-   ```
-   [Click here to authenticate with Meta Ads API](https://www.facebook.com/dialog/oauth?...)
-   ```
+If you encounter errors like `(#200) Provide valid app ID`, check the following:
 
-   Just click the link, complete the authorization in your browser, and the token will be automatically captured and stored.
+1. Ensure you've set up a Meta Developer App correctly
+2. Verify that you're passing the correct App ID using one of these methods:
+   - Set the `META_APP_ID` environment variable: `export META_APP_ID=your_app_id`
+   - Pass it as a command-line argument: `meta-ads-mcp --app-id your_app_id`
 
-2. **Command Line Authentication**
+#### Authentication Errors
 
-   You can authenticate directly from the command line:
+Authentication errors can be tracked in the log file. Check for:
+- Token expiration issues
+- App permission problems
+- Connection errors
 
-   ```bash
-   uvx meta-ads-mcp --login --app-id YOUR_APP_ID
-   ```
+### Debugging Command
 
-### Token Caching
+For specific image download issues, use the built-in diagnostic tool:
+
+```python
+# Using direct tool call
+mcp_meta_ads_debug_image_download(ad_id="your_ad_id")
+```
+
+This will give you detailed information about the download process and potential issues.
+
+## Running with Different App IDs
+
+If you need to use different Meta App IDs for different purposes:
+
+```bash
+# Using environment variable
+export META_APP_ID=your_app_id
+uvx meta-ads-mcp
+
+# Or using command line argument
+uvx meta-ads-mcp --app-id=your_app_id
+```
 
-Tokens are cached in a platform-specific secure location:
-- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
-- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
-- Linux: `~/.config/meta-ads-mcp/token_cache.json`
+## Privacy and Security
 
-You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
+The Meta Ads MCP follows security best practices:
 
-## Environment Variables
+1. Tokens are cached in a platform-specific secure location:
+   - Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
+   - macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
+   - Linux: `~/.config/meta-ads-mcp/token_cache.json`
 
-You can set the following environment variables instead of passing them as arguments:
+2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
 
-- `META_APP_ID`: Your Meta App ID (Client ID)
+3. You can set the following environment variables instead of passing them as arguments:
+   - `META_APP_ID`: Your Meta App ID (Client ID)
 
 ## Testing
 
@@ -305,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.3 → meta_ads_mcp-0.2.5}/meta-ads-mcp

@@ -10,5 +10,4 @@ This script provides the command-line entry point for the Meta Ads MCP package.
 from meta_ads_mcp import main
 
 if __name__ == "__main__":
-    print("RUNNING LOCAL SCRIPT VERSION OF META ADS MCP")
     main() 

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

@@ -7,9 +7,27 @@ with the Claude LLM.
 
 from meta_ads_mcp.core.server import main
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
-__all__ = ["main"]
+__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',
+    'get_insights',
+    'debug_image_download',
+    'get_login_link',
+    'login_cli',
+    'main'
+]
 
 # Import key functions to make them available at package level
 from .core import (
@@ -27,9 +45,9 @@ from .core import (
     get_ad_image,
     get_insights,
     debug_image_download,
-    save_ad_image_via_api,
     get_login_link,
     login_cli,
+    main
 )
 
 # Define a main function to be used as a package entry point