meta-ads-mcp 0.3.6__tar.gz → 0.3.8__tar.gz

meta_ads_mcp-0.3.8/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  # Allow manual triggering for testing
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+      contents: read
+
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build package
+      run: python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        # Using trusted publishing (no API token needed)
+        # Make sure to configure trusted publishing in PyPI project settings
+        verbose: true 

meta_ads_mcp-0.3.8/.github/workflows/test.yml

@@ -0,0 +1,56 @@
+name: Test and Build
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build pytest
+        pip install -e .
+
+    - name: Test package build
+      run: python -m build
+
+    - name: Test package installation
+      run: |
+        pip install dist/*.whl
+        python -c "import meta_ads_mcp; print('Package imported successfully')"
+
+  validate-version:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v4
+      
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+        
+    - name: Check version bump
+      run: |
+        # This is a simple check - you might want to make it more sophisticated
+        echo "Current version in pyproject.toml:"
+        grep "version = " pyproject.toml 

{meta_ads_mcp-0.3.6 → meta_ads_mcp-0.3.8}/.gitignore

@@ -20,3 +20,13 @@ uv.lock
 
 # Generated content
 ad_creatives/
+
+# Debug and development files
+debug/
+*.pyc
+.pytest_cache/
+
+# Keep organized directories but exclude some debug content
+!debug/README.md
+
+internal/

meta_ads_mcp-0.3.8/CUSTOM_META_APP.md

@@ -0,0 +1,110 @@
+# Using a Custom Meta Developer App
+
+This guide explains how to use Meta Ads MCP with your own Meta Developer App. Note that this is an alternative method - we recommend using [Pipeboard authentication](README.md) for a simpler setup.
+
+## Create a Meta Developer App
+
+Before using direct Meta authentication, 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 "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
+
+## Installation & Usage
+
+When using your own Meta app, you'll need to provide the App ID:
+
+```bash
+# Using uvx
+uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
+
+# Using pip installation
+python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
+```
+
+## Configuration
+
+### Cursor or Claude Desktop Integration
+
+Add this to your `claude_desktop_config.json` or `~/.cursor/mcp.json`:
+
+```json
+"mcpServers": {
+  "meta-ads": {
+    "command": "uvx",
+    "args": ["meta-ads-mcp", "--app-id", "YOUR_META_ADS_APP_ID"]
+  }
+}
+```
+
+## Authentication Flow
+
+When using direct Meta OAuth, the MCP uses Meta's OAuth 2.0 authentication flow:
+
+1. Starts a local callback server on your machine
+2. Opens a browser window to authenticate with Meta
+3. Asks you to authorize the app
+4. Redirects back to the local server to extract and store the token securely
+
+## Environment Variables
+
+You can use these environment variables instead of command-line arguments:
+
+```bash
+# Your Meta App ID
+export META_APP_ID=your_app_id
+uvx meta-ads-mcp
+
+# Or provide a direct access token (bypasses local cache)
+export META_ACCESS_TOKEN=your_access_token
+uvx meta-ads-mcp
+```
+
+## Testing
+
+### CLI Testing
+
+Run the test script to verify authentication:
+
+```bash
+# Basic test
+python test_meta_ads_auth.py --app-id YOUR_APP_ID
+
+# Force new login
+python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
+```
+
+### LLM Interface Testing
+
+When using direct Meta authentication:
+1. Test authentication by calling the `mcp_meta_ads_get_login_link` tool
+2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
+3. Check specific account details with `mcp_meta_ads_get_account_info`
+
+## Troubleshooting
+
+### Authentication Issues
+
+1. App ID Issues
+   - If you encounter errors like `(#200) Provide valid app ID`, verify your App ID is correct
+   - Make sure you've completed the app setup steps above
+   - Check that your app has the Marketing API product added
+
+2. OAuth Flow
+   - Run with `--force-login` to get a fresh token: `uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login`
+   - Make sure the terminal has permissions to open a browser window
+   - Check that the callback server can run on port 8888
+
+3. Direct Token Usage
+   - If you have a valid access token, you can bypass the OAuth flow:
+   - `export META_ACCESS_TOKEN=your_access_token`
+   - This will ignore the local token cache
+
+### API Errors
+
+If you receive errors from the Meta API:
+1. Verify your app has the Marketing API product added
+2. Ensure the user has appropriate permissions on the ad accounts
+3. Check if there are rate limits or other restrictions on your app 

{meta_ads_mcp-0.3.6 → meta_ads_mcp-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.3.6
+Version: 0.3.8
 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,9 +11,9 @@ 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.9.6
+Requires-Python: >=3.10
 Requires-Dist: httpx>=0.26.0
-Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: mcp[cli]>=1.9.0
 Requires-Dist: pathlib>=1.0.1
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: python-dateutil>=2.8.2
@@ -27,9 +27,35 @@ 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.
 
-**Screenshot**: Using an LLM to understand your ad performance:
+[![Meta Ads MCP Server Demo](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)
 
-![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)
+
+## Community & Support
+
+- [Discord](https://discord.gg/hNxpJcqM52). Join the community.
+- [Email Support](info@pipeboard.co). Email us for support.
+  
+## Quick Start
+
+1. Sign-up to [Pipeboard](https://pipeboard.co) to authenticate with Meta (alternatively, you can setup your own [custom meta app](CUSTOM_META_APP.md))
+2. Get your Pipeboard token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens) 
+3. Add this configuration to your MCP client:
+
+```json
+"mcpServers": {
+  "meta-ads": {
+    "command": "uvx",
+    "args": ["meta-ads-mcp"],
+    "env": {
+      "PIPEBOARD_API_TOKEN": "your_pipeboard_token"  // Get your token at https://pipeboard.co/api-tokens
+    }
+  }
+}
+```
+
+That's it! You can now use Meta Ads MCP in your favorite MCP client.
+
+> **Note**: If you prefer to use your own Meta Developer App instead of Pipeboard authentication, see [CUSTOM_META_APP.md](CUSTOM_META_APP.md) for instructions.
 
 ## Features
 
@@ -44,56 +70,80 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 - **Simple Authentication**: Easy setup with secure OAuth authentication
 - **Cross-Platform Support**: Works on Windows, macOS, and Linux
 
-## Installation
+## Advanced Setup
 
-### Using uv (recommended)
+### Development Installation
 
-When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
+If you're contributing to the project or need to run it directly:
 
 ```bash
-# Run with Meta authentication
-uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
+# From the repository root
+uv pip install -e .
 ```
 
-If you want to install the package:
+## Privacy and Security
 
-```bash
-uv pip install meta-ads-mcp
-```
+The Meta Ads MCP follows security best practices:
 
-For development (if you've cloned the repository):
+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`
 
-```bash
-# From the repository root
-uv pip install -e .
-```
+2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
 
-### Using pip
+## Testing
 
-Alternatively, you can install meta-ads-mcp via pip:
+### LLM Interface Testing
 
-```bash
-pip install meta-ads-mcp
-```
+When using the Meta Ads MCP with an LLM interface (like Claude):
 
-After installation, you can run it as:
+1. Ensure the PIPEBOARD_API_TOKEN environment variable is set
+2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
+3. Check specific account details with `mcp_meta_ads_get_account_info`
 
-```bash
-# Run with Meta authentication
-python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
-```
+## Troubleshooting
+
+### Authentication Issues
+
+If you encounter authentication issues:
+
+1. Verify your Pipeboard setup:
+   - Check that `PIPEBOARD_API_TOKEN` is set correctly
+   - Verify your token in the Pipeboard dashboard
+   - Try forcing a new login: `python test_pipeboard_auth.py --force-login`
+
+2. When using the LLM interface:
+   - Ensure the PIPEBOARD_API_TOKEN environment variable is set
+   - Check that the callback server is running properly
+
+### API Errors
+
+If you receive errors from the Meta API:
+1. Ensure the user has appropriate permissions on the ad accounts
+2. Check if there are rate limits or other restrictions
+3. Verify your Pipeboard token hasn't expired
+
+## 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` 
 
 ## Configuration
 
-### Create a Meta Developer App (Required)
+### Pipeboard Authentication
 
-Before using the MCP server, you'll need to set up a Meta Developer App:
+The easiest way to use Meta Ads MCP is with Pipeboard authentication:
 
-1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
-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
+1. Sign up at [Pipeboard.co](https://pipeboard.co) and generate an API token
+2. Set the environment variable:
+   ```bash
+   export PIPEBOARD_API_TOKEN=your_pipeboard_token
+   ```
+3. Run meta-ads-mcp - it will handle authentication automatically
 
 ### Usage with Cursor or Claude Desktop
 
@@ -103,11 +153,18 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
 "mcpServers": {
   "meta-ads": {
     "command": "uvx",
-    "args": ["meta-ads-mcp", "--app-id", "YOUR_META_ADS_APP_ID"]
+    "args": ["meta-ads-mcp"],
+    "env": {
+      "PIPEBOARD_API_TOKEN": "your_pipeboard_token"  // Get your token at https://pipeboard.co
+    }
   }
 }
 ```
 
+## Transports
+
+Meta Ads MCP uses **stdio transport** by default, which works with MCP clients like Claude Desktop and Cursor. For web applications and direct HTTP API access, see [STREAMABLE_HTTP_SETUP.md](STREAMABLE_HTTP_SETUP.md) for streamable HTTP transport configuration.
+
 ### Available MCP Tools
 
 1. `mcp_meta_ads_get_ad_accounts`
@@ -319,157 +376,3 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
       - `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:
-
-When authenticating, it will:
-
-1. Start a local callback server on your machine
-2. Open a browser window to authenticate with Meta
-3. Ask you to authorize the app
-4. Redirect back to the local server to extract and store the token securely
-
-This method requires you to [create a Meta Developer App](#create-a-meta-developer-app) as described above.
-
-## 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`
-
-### Common Issues
-
-#### Authentication Issues
-
-If you encounter errors like `(#200) Provide valid app ID`, check the following:
-- Ensure you've set up a Meta Developer App correctly
-- 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`
-
-#### API Errors
-
-If you receive errors from the Meta API:
-
-1. Verify your app has the Marketing API product added
-2. Ensure the user has appropriate permissions on the ad accounts
-3. Check if there are rate limits or other restrictions on your app
-
-### Debugging Command
-
-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
-```
-
-## Privacy and Security
-
-The Meta Ads MCP follows security best practices:
-
-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`
-
-2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
-
-3. You can set the `META_APP_ID` environment variable instead of passing it as an argument:
-   ```bash
-   export META_APP_ID=your_app_id
-   uvx meta-ads-mcp
-   ```
-
-4. You can provide a direct access token using the `META_ACCESS_TOKEN` environment variable. This bypasses both the local token cache and the Pipeboard authentication method:
-   ```bash
-   export META_ACCESS_TOKEN=your_access_token
-   uvx meta-ads-mcp
-   ```
-   This is useful for CI/CD pipelines or when you already have a valid access token from another source.
-
-## Testing
-
-### CLI Testing
-
-Run the test script to verify authentication and basic functionality:
-
-```bash
-python test_meta_ads_auth.py --app-id YOUR_APP_ID
-```
-
-Use the `--force-login` flag to force a new authentication even if a cached token exists:
-
-```bash
-python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
-```
-
-### LLM Interface Testing
-
-When using the Meta Ads MCP with an LLM interface (like Claude):
-
-1. Test authentication by calling the `mcp_meta_ads_get_login_link` tool
-2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
-3. Check specific account details with `mcp_meta_ads_get_account_info`
-
-These functions will automatically handle authentication if needed and provide a clickable login link if required.
-
-## Troubleshooting
-
-### Authentication Issues
-
-If you encounter authentication issues:
-
-1. When using the LLM interface:
-   - Use the `mcp_meta_ads_get_login_link` tool to generate a fresh authentication link
-   - Ensure you click the link and complete the authorization flow in your browser
-   - Check that the callback server is running properly (the tool will report this)
-
-2. When using direct Meta OAuth:
-   - Run with `--force-login` to get a fresh token: `uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login`
-   - Make sure the terminal has permissions to open a browser window
-
-3. Skip authentication entirely by providing a token directly:
-   - If you already have a valid access token, you can bypass the authentication flow:
-   - `export META_ACCESS_TOKEN=your_access_token`
-   - This will ignore both the local token cache and the Pipeboard authentication
-
-### API Errors
-
-If you receive errors from the Meta API:
-
-1. Verify your app has the Marketing API product added
-2. Ensure the user has appropriate permissions on the ad accounts
-3. Check if there are rate limits or other restrictions on your app
-
-## Versioning
-
-You can check the current version of the package:
-
-```python
-import meta_ads_mcp
-print(meta_ads_mcp.__version__)
-```