meta-ads-mcp 0.3.0__tar.gz → 0.3.2__tar.gz

meta_ads_mcp-0.3.2/Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends gcc && \
+    rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Install uv
+RUN pip install --upgrade pip && \
+    pip install uv
+
+# Copy requirements file
+COPY requirements.txt .
+
+# Install dependencies using uv with --system flag
+RUN uv pip install --system -r requirements.txt
+
+# Copy the rest of the application
+COPY . .
+
+# Command to run the Meta Ads MCP server
+CMD ["python", "-m", "meta_ads_mcp"] 

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.3.0
+Version: 0.3.2
 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>
+Author-email: Yves Junqueira <yves.junqueira@gmail.com>
 License: MIT
 License-File: LICENSE
 Keywords: ads,api,claude,facebook,mcp,meta
@@ -31,7 +31,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
   <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.
+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)
 
@@ -55,11 +55,7 @@ Screenhot: using an LLM to understand your ad performance.
 When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
 
 ```bash
-# RECOMMENDED: Use with Pipeboard authentication
-export PIPEBOARD_API_TOKEN=your_pipeboard_token  # Get your token at https://pipeboard.co
-uvx meta-ads-mcp
-
-# Alternative: Use with direct Meta authentication
+# Run with Meta authentication
 uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
 ```
 
@@ -87,50 +83,26 @@ pip install meta-ads-mcp
 After installation, you can run it as:
 
 ```bash
-# RECOMMENDED: Use with Pipeboard authentication
-export PIPEBOARD_API_TOKEN=your_pipeboard_token  # Get your token at https://pipeboard.co
-python -m meta_ads_mcp
-
-# Alternative: Use with direct Meta authentication
+# Run with Meta authentication
 python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
 ```
 
 ## Configuration
 
-### Quick Start with Pipeboard Authentication (Recommended)
-
-The easiest way to configure Meta Ads MCP is using Pipeboard authentication:
+### Create a Meta Developer App (Required)
 
-1. Sign up at [Pipeboard.co](https://pipeboard.co) and generate an API token - **Get your free token at [https://pipeboard.co](https://pipeboard.co)**
-2. Set the environment variable:
-   ```bash
-   export PIPEBOARD_API_TOKEN=your_pipeboard_token   # Token obtainable via https://pipeboard.co
-   ```
-3. Run meta-ads-mcp without needing to set up a Meta Developer App:
-   ```bash
-   uvx meta-ads-mcp
-   ```
+Before using the MCP server, you'll need to set up a Meta Developer App:
 
-This method provides longer-lived tokens (60 days), simplified setup, and automatic token renewal.
+1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
+2. Choose the "Consumer" 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
 
 ### Usage with Cursor or Claude Desktop
 
 Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cursor/mcp.json` to integrate with Cursor:
 
-```json
-"mcpServers": {
-  "meta-ads": {
-    "command": "uvx",
-    "args": ["meta-ads-mcp"],
-    "env": {
-      "PIPEBOARD_API_TOKEN": "your_pipeboard_token"  // Token obtainable via https://pipeboard.co
-    }
-  }
-}
-```
-
-Or if you prefer direct Meta authentication (using your own Facebook app):
-
 ```json
 "mcpServers": {
   "meta-ads": {
@@ -274,54 +246,13 @@ Or if you prefer direct Meta authentication (using your own Facebook app):
 
 16. `mcp_meta_ads_get_login_link`
     - Get a clickable login link for Meta Ads authentication
-    - NOTE: This method should only be used if you're using your own Facebook app. If using Pipeboard authentication (recommended), set the PIPEBOARD_API_TOKEN environment variable instead (token obtainable via https://pipeboard.co).
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: A clickable resource link for Meta authentication
 
-## Create a Meta Developer App
-
-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
-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
-
 ## Authentication
 
-The Meta Ads MCP supports two authentication methods:
-
-### 1. Pipeboard Authentication (Recommended ⭐)
-
-This method uses [Pipeboard.co](https://pipeboard.co) to manage Meta API authentication, providing longer-lived tokens and a simplified flow:
-
-1. **Get your Pipeboard token**: Sign up at [https://pipeboard.co](https://pipeboard.co) to generate your free API token
-2. Set the `PIPEBOARD_API_TOKEN` environment variable with your token: 
-   ```bash
-   export PIPEBOARD_API_TOKEN=your_pipeboard_token
-   ```
-3. Run the Meta Ads MCP normally - it will automatically detect and use Pipeboard authentication:
-   ```bash
-   uvx meta-ads-mcp
-   ```
-4. The first time you run a command, you'll be provided with a login URL to authorize with Meta
-
-**Benefits of Pipeboard authentication:**
-- ✅ Longer-lived tokens (60 days)
-- ✅ No need to configure a Meta Developer App
-- ✅ Simpler setup with just an API token
-- ✅ Automatic token renewal
-
-To test the Pipeboard authentication flow:
-```bash
-python test_pipeboard_auth.py --api-token YOUR_PIPEBOARD_TOKEN
-```
-
-### 2. Direct Meta OAuth (Legacy)
-
-The traditional OAuth 2.0 flow designed for desktop apps. This method should only be used if you are using your own Facebook app instead of Pipeboard.
+The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:
 
 When authenticating, it will:
 
@@ -330,7 +261,7 @@ When authenticating, it will:
 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) first.
+This method requires you to [create a Meta Developer App](#create-a-meta-developer-app) as described above.
 
 ## Troubleshooting and Logging
 
@@ -348,19 +279,11 @@ Log files are stored in a platform-specific location:
 
 #### Authentication Issues
 
-If you're having authentication problems:
-
-1. **Recommended: Use Pipeboard Authentication**
-   - Set `export PIPEBOARD_API_TOKEN=your_token` and retry
-   - This provides longer-lived tokens and better reliability
-   - Verify your token in the Pipeboard dashboard
-
-2. For App ID issues (when using direct authentication):
-   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`
+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
 
@@ -399,15 +322,24 @@ uvx meta-ads-mcp --app-id=your_app_id
 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` or `%APPDATA%\meta-ads-mcp\pipeboard_token_cache.json`
-   - macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json` or `~/Library/Application Support/meta-ads-mcp/pipeboard_token_cache.json`
-   - Linux: `~/.config/meta-ads-mcp/token_cache.json` or `~/.config/meta-ads-mcp/pipeboard_token_cache.json`
+   - 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 following environment variables instead of passing them as arguments:
-   - `META_APP_ID`: Your Meta App ID (Client ID) - for direct OAuth method
-   - `PIPEBOARD_API_TOKEN`: Your Pipeboard API token - for Pipeboard authentication method
+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
 
@@ -429,10 +361,9 @@ python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
 
 When using the Meta Ads MCP with an LLM interface (like Claude):
 
-1. If using direct Meta authentication (your own Facebook app), test authentication by calling the `mcp_meta_ads_get_login_link` tool
-2. If using Pipeboard authentication (recommended), ensure the PIPEBOARD_API_TOKEN environment variable is set (token obtainable via https://pipeboard.co)
-3. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
-4. Check specific account details with `mcp_meta_ads_get_account_info`
+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.
 
@@ -443,20 +374,19 @@ These functions will automatically handle authentication if needed and provide a
 If you encounter authentication issues:
 
 1. When using the LLM interface:
-   - If using direct Meta authentication (your own Facebook app), use the `mcp_meta_ads_get_login_link` tool to generate a fresh authentication link
-   - If using Pipeboard authentication (recommended), ensure the PIPEBOARD_API_TOKEN environment variable is set (token obtainable via https://pipeboard.co)
+   - 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 Pipeboard authentication:
-   - Verify your `PIPEBOARD_API_TOKEN` is set correctly (token obtainable via https://pipeboard.co)
-   - Check if you need to complete the authorization process by visiting the provided login URL
-   - Try forcing a new login: `python test_pipeboard_auth.py --force-login`
-
-3. When using direct Meta OAuth:
+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:

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/README.md

@@ -8,7 +8,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
   <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.
+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)
 
@@ -32,11 +32,7 @@ Screenhot: using an LLM to understand your ad performance.
 When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
 
 ```bash
-# RECOMMENDED: Use with Pipeboard authentication
-export PIPEBOARD_API_TOKEN=your_pipeboard_token  # Get your token at https://pipeboard.co
-uvx meta-ads-mcp
-
-# Alternative: Use with direct Meta authentication
+# Run with Meta authentication
 uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
 ```
 
@@ -64,50 +60,26 @@ pip install meta-ads-mcp
 After installation, you can run it as:
 
 ```bash
-# RECOMMENDED: Use with Pipeboard authentication
-export PIPEBOARD_API_TOKEN=your_pipeboard_token  # Get your token at https://pipeboard.co
-python -m meta_ads_mcp
-
-# Alternative: Use with direct Meta authentication
+# Run with Meta authentication
 python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
 ```
 
 ## Configuration
 
-### Quick Start with Pipeboard Authentication (Recommended)
-
-The easiest way to configure Meta Ads MCP is using Pipeboard authentication:
+### Create a Meta Developer App (Required)
 
-1. Sign up at [Pipeboard.co](https://pipeboard.co) and generate an API token - **Get your free token at [https://pipeboard.co](https://pipeboard.co)**
-2. Set the environment variable:
-   ```bash
-   export PIPEBOARD_API_TOKEN=your_pipeboard_token   # Token obtainable via https://pipeboard.co
-   ```
-3. Run meta-ads-mcp without needing to set up a Meta Developer App:
-   ```bash
-   uvx meta-ads-mcp
-   ```
+Before using the MCP server, you'll need to set up a Meta Developer App:
 
-This method provides longer-lived tokens (60 days), simplified setup, and automatic token renewal.
+1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
+2. Choose the "Consumer" 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
 
 ### Usage with Cursor or Claude Desktop
 
 Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cursor/mcp.json` to integrate with Cursor:
 
-```json
-"mcpServers": {
-  "meta-ads": {
-    "command": "uvx",
-    "args": ["meta-ads-mcp"],
-    "env": {
-      "PIPEBOARD_API_TOKEN": "your_pipeboard_token"  // Token obtainable via https://pipeboard.co
-    }
-  }
-}
-```
-
-Or if you prefer direct Meta authentication (using your own Facebook app):
-
 ```json
 "mcpServers": {
   "meta-ads": {
@@ -251,54 +223,13 @@ Or if you prefer direct Meta authentication (using your own Facebook app):
 
 16. `mcp_meta_ads_get_login_link`
     - Get a clickable login link for Meta Ads authentication
-    - NOTE: This method should only be used if you're using your own Facebook app. If using Pipeboard authentication (recommended), set the PIPEBOARD_API_TOKEN environment variable instead (token obtainable via https://pipeboard.co).
     - Inputs:
       - `access_token` (optional): Meta API access token (will use cached token if not provided)
     - Returns: A clickable resource link for Meta authentication
 
-## Create a Meta Developer App
-
-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
-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
-
 ## Authentication
 
-The Meta Ads MCP supports two authentication methods:
-
-### 1. Pipeboard Authentication (Recommended ⭐)
-
-This method uses [Pipeboard.co](https://pipeboard.co) to manage Meta API authentication, providing longer-lived tokens and a simplified flow:
-
-1. **Get your Pipeboard token**: Sign up at [https://pipeboard.co](https://pipeboard.co) to generate your free API token
-2. Set the `PIPEBOARD_API_TOKEN` environment variable with your token: 
-   ```bash
-   export PIPEBOARD_API_TOKEN=your_pipeboard_token
-   ```
-3. Run the Meta Ads MCP normally - it will automatically detect and use Pipeboard authentication:
-   ```bash
-   uvx meta-ads-mcp
-   ```
-4. The first time you run a command, you'll be provided with a login URL to authorize with Meta
-
-**Benefits of Pipeboard authentication:**
-- ✅ Longer-lived tokens (60 days)
-- ✅ No need to configure a Meta Developer App
-- ✅ Simpler setup with just an API token
-- ✅ Automatic token renewal
-
-To test the Pipeboard authentication flow:
-```bash
-python test_pipeboard_auth.py --api-token YOUR_PIPEBOARD_TOKEN
-```
-
-### 2. Direct Meta OAuth (Legacy)
-
-The traditional OAuth 2.0 flow designed for desktop apps. This method should only be used if you are using your own Facebook app instead of Pipeboard.
+The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:
 
 When authenticating, it will:
 
@@ -307,7 +238,7 @@ When authenticating, it will:
 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) first.
+This method requires you to [create a Meta Developer App](#create-a-meta-developer-app) as described above.
 
 ## Troubleshooting and Logging
 
@@ -325,19 +256,11 @@ Log files are stored in a platform-specific location:
 
 #### Authentication Issues
 
-If you're having authentication problems:
-
-1. **Recommended: Use Pipeboard Authentication**
-   - Set `export PIPEBOARD_API_TOKEN=your_token` and retry
-   - This provides longer-lived tokens and better reliability
-   - Verify your token in the Pipeboard dashboard
-
-2. For App ID issues (when using direct authentication):
-   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`
+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
 
@@ -376,15 +299,24 @@ uvx meta-ads-mcp --app-id=your_app_id
 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` or `%APPDATA%\meta-ads-mcp\pipeboard_token_cache.json`
-   - macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json` or `~/Library/Application Support/meta-ads-mcp/pipeboard_token_cache.json`
-   - Linux: `~/.config/meta-ads-mcp/token_cache.json` or `~/.config/meta-ads-mcp/pipeboard_token_cache.json`
+   - 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 following environment variables instead of passing them as arguments:
-   - `META_APP_ID`: Your Meta App ID (Client ID) - for direct OAuth method
-   - `PIPEBOARD_API_TOKEN`: Your Pipeboard API token - for Pipeboard authentication method
+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
 
@@ -406,10 +338,9 @@ python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
 
 When using the Meta Ads MCP with an LLM interface (like Claude):
 
-1. If using direct Meta authentication (your own Facebook app), test authentication by calling the `mcp_meta_ads_get_login_link` tool
-2. If using Pipeboard authentication (recommended), ensure the PIPEBOARD_API_TOKEN environment variable is set (token obtainable via https://pipeboard.co)
-3. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
-4. Check specific account details with `mcp_meta_ads_get_account_info`
+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.
 
@@ -420,20 +351,19 @@ These functions will automatically handle authentication if needed and provide a
 If you encounter authentication issues:
 
 1. When using the LLM interface:
-   - If using direct Meta authentication (your own Facebook app), use the `mcp_meta_ads_get_login_link` tool to generate a fresh authentication link
-   - If using Pipeboard authentication (recommended), ensure the PIPEBOARD_API_TOKEN environment variable is set (token obtainable via https://pipeboard.co)
+   - 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 Pipeboard authentication:
-   - Verify your `PIPEBOARD_API_TOKEN` is set correctly (token obtainable via https://pipeboard.co)
-   - Check if you need to complete the authorization process by visiting the provided login URL
-   - Try forcing a new login: `python test_pipeboard_auth.py --force-login`
-
-3. When using direct Meta OAuth:
+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:

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/__init__.py

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

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/api.py

@@ -22,7 +22,7 @@ from http.server import HTTPServer, BaseHTTPRequestHandler
 mcp_server = FastMCP("meta-ads-generated", use_consistent_tool_format=True)
 
 # Constants
-META_GRAPH_API_VERSION = "v20.0"
+META_GRAPH_API_VERSION = "v22.0"
 META_GRAPH_API_BASE = f"https://graph.facebook.com/{META_GRAPH_API_VERSION}"
 USER_AGENT = "meta-ads-mcp/1.0"
 
@@ -48,6 +48,13 @@ callback_server_port = None
 # Global token container for communication between threads
 token_container = {"token": None, "expires_in": None, "user_id": None}
 
+# Add these at the top of the file with the other global variables
+callback_server_instance = None
+server_shutdown_timer = None
+
+# Add this near other constants in the file
+CALLBACK_SERVER_TIMEOUT = 180  # 3 minutes timeout
+
 # Configuration class to store app ID and other config
 class MetaConfig:
     _instance = None
@@ -253,7 +260,7 @@ class AuthManager:
     def get_auth_url(self) -> str:
         """Generate the Facebook OAuth URL for desktop app flow"""
         return (
-            f"https://www.facebook.com/v18.0/dialog/oauth?"
+            f"https://www.facebook.com/v22.0/dialog/oauth?"
             f"client_id={self.app_id}&"
             f"redirect_uri={self.redirect_uri}&"
             f"scope={AUTH_SCOPE}&"
@@ -1875,13 +1882,50 @@ async def try_multiple_download_methods(url: str) -> Optional[bytes]:
     
     return None
 
+def shutdown_callback_server():
+    """Shutdown the callback server if it's running"""
+    global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
+    
+    with callback_server_lock:
+        if not callback_server_running:
+            print("Callback server is not running")
+            return
+        
+        if server_shutdown_timer is not None:
+            server_shutdown_timer.cancel()
+            server_shutdown_timer = None
+        
+        print(f"Shutting down callback server on port {callback_server_port}")
+        
+        # Shutdown the server if it exists
+        if callback_server_instance:
+            try:
+                callback_server_instance.shutdown()
+                callback_server_instance = None
+                callback_server_running = False
+                print("Callback server has been shut down")
+            except Exception as e:
+                print(f"Error shutting down callback server: {e}")
+        else:
+            print("No server instance to shut down")
+
 def start_callback_server():
     """Start the callback server if it's not already running"""
-    global callback_server_thread, callback_server_running, callback_server_port
+    global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
     
     with callback_server_lock:
         if callback_server_running:
             print(f"Callback server already running on port {callback_server_port}")
+            
+            # Reset the shutdown timer if one exists
+            if server_shutdown_timer is not None:
+                server_shutdown_timer.cancel()
+            
+            server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
+            server_shutdown_timer.daemon = True
+            server_shutdown_timer.start()
+            print(f"Reset server shutdown timer to {CALLBACK_SERVER_TIMEOUT} seconds")
+            
             return callback_server_port
         
         # Find an available port
@@ -1913,6 +1957,7 @@ def start_callback_server():
             
             # Create and start server in a daemon thread
             server = HTTPServer(('localhost', port), handler_class)
+            callback_server_instance = server
             print(f"Callback server starting on port {port}")
             
             # Create a simple flag to signal when the server is ready
@@ -1942,6 +1987,15 @@ def start_callback_server():
             
             callback_server_running = True
             
+            # Set a timer to shutdown the server after CALLBACK_SERVER_TIMEOUT seconds
+            if server_shutdown_timer is not None:
+                server_shutdown_timer.cancel()
+            
+            server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
+            server_shutdown_timer.daemon = True
+            server_shutdown_timer.start()
+            print(f"Server will automatically shut down after {CALLBACK_SERVER_TIMEOUT} seconds of inactivity")
+            
             # Verify the server is actually accepting connections
             try:
                 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/core/adsets.py

@@ -6,7 +6,7 @@ from .api import meta_api_tool, make_api_request
 from .accounts import get_ad_accounts
 from .server import mcp_server
 import asyncio
-from .callback_server import start_callback_server, update_confirmation
+from .callback_server import start_callback_server, shutdown_callback_server, update_confirmation
 import urllib.parse
 
 

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/core/api.py

@@ -6,11 +6,11 @@ import httpx
 import asyncio
 import functools
 import os
-from .auth import needs_authentication, get_current_access_token, auth_manager, start_callback_server
+from .auth import needs_authentication, get_current_access_token, auth_manager, start_callback_server, shutdown_callback_server
 from .utils import logger
 
 # Constants
-META_GRAPH_API_VERSION = "v20.0"
+META_GRAPH_API_VERSION = "v22.0"
 META_GRAPH_API_BASE = f"https://graph.facebook.com/{META_GRAPH_API_VERSION}"
 USER_AGENT = "meta-ads-mcp/1.0"
 

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/core/auth.py

@@ -13,9 +13,10 @@ import requests
 
 # Import from the new callback server module
 from .callback_server import (
-    start_callback_server, 
+    start_callback_server,
+    shutdown_callback_server,
     token_container,
-    update_confirmation
+    callback_server_port
 )
 
 # Import the new Pipeboard authentication
@@ -187,7 +188,7 @@ class AuthManager:
     def get_auth_url(self) -> str:
         """Generate the Facebook OAuth URL for desktop app flow"""
         return (
-            f"https://www.facebook.com/v18.0/dialog/oauth?"
+            f"https://www.facebook.com/v22.0/dialog/oauth?"
             f"client_id={self.app_id}&"
             f"redirect_uri={self.redirect_uri}&"
             f"scope={AUTH_SCOPE}&"
@@ -359,7 +360,7 @@ def exchange_token_for_long_lived(short_lived_token):
             return None
             
         # Make the API request to exchange the token
-        url = "https://graph.facebook.com/v18.0/oauth/access_token"
+        url = "https://graph.facebook.com/v22.0/oauth/access_token"
         params = {
             "grant_type": "fb_exchange_token",
             "client_id": app_id,
@@ -398,6 +399,16 @@ def exchange_token_for_long_lived(short_lived_token):
 
 async def get_current_access_token() -> Optional[str]:
     """Get the current access token from auth manager"""
+    # Check for environment variable first - this takes highest precedence
+    env_token = os.environ.get("META_ACCESS_TOKEN")
+    if env_token:
+        logger.debug("Using access token from META_ACCESS_TOKEN environment variable")
+        # Basic validation
+        if len(env_token) < 20:  # Most Meta tokens are much longer
+            logger.error(f"TOKEN VALIDATION FAILED: Token from environment variable appears malformed (length: {len(env_token)})")
+            return None
+        return env_token
+        
     # Use the singleton auth manager
     global auth_manager
     

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/core/authentication.py

@@ -4,7 +4,7 @@ import json
 import asyncio
 import os
 from .api import meta_api_tool
-from .auth import start_callback_server, auth_manager, get_current_access_token
+from .auth import start_callback_server, shutdown_callback_server, auth_manager, get_current_access_token
 from .server import mcp_server
 from .utils import logger, META_APP_SECRET
 from .pipeboard_auth import pipeboard_auth_manager

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/core/callback_server.py

@@ -24,6 +24,11 @@ callback_server_thread = None
 callback_server_lock = threading.Lock()
 callback_server_running = False
 callback_server_port = None
+callback_server_instance = None
+server_shutdown_timer = None
+
+# Timeout in seconds before shutting down the callback server
+CALLBACK_SERVER_TIMEOUT = 180  # 3 minutes timeout
 
 
 class CallbackHandler(BaseHTTPRequestHandler):
@@ -877,6 +882,35 @@ class CallbackHandler(BaseHTTPRequestHandler):
         return
 
 
+def shutdown_callback_server():
+    """
+    Shutdown the callback server if it's running
+    """
+    global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
+    
+    with callback_server_lock:
+        if not callback_server_running:
+            print("Callback server is not running")
+            return
+        
+        if server_shutdown_timer is not None:
+            server_shutdown_timer.cancel()
+            server_shutdown_timer = None
+        
+        print(f"Shutting down callback server on port {callback_server_port}")
+        
+        # Shutdown the server if it exists
+        if callback_server_instance:
+            try:
+                callback_server_instance.shutdown()
+                callback_server_instance = None
+                callback_server_running = False
+                print("Callback server has been shut down")
+            except Exception as e:
+                print(f"Error shutting down callback server: {e}")
+        else:
+            print("No server instance to shut down")
+
 def start_callback_server() -> int:
     """
     Start the callback server if it's not already running
@@ -884,11 +918,21 @@ def start_callback_server() -> int:
     Returns:
         Port number the server is running on
     """
-    global callback_server_thread, callback_server_running, callback_server_port
+    global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
     
     with callback_server_lock:
         if callback_server_running:
             print(f"Callback server already running on port {callback_server_port}")
+            
+            # Reset the shutdown timer if one exists
+            if server_shutdown_timer is not None:
+                server_shutdown_timer.cancel()
+            
+            server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
+            server_shutdown_timer.daemon = True
+            server_shutdown_timer.start()
+            print(f"Reset server shutdown timer to {CALLBACK_SERVER_TIMEOUT} seconds")
+            
             return callback_server_port
         
         # Find an available port
@@ -909,6 +953,7 @@ def start_callback_server() -> int:
         try:
             # Create and start server in a daemon thread
             server = HTTPServer(('localhost', port), CallbackHandler)
+            callback_server_instance = server
             print(f"Callback server starting on port {port}")
             
             # Create a simple flag to signal when the server is ready
@@ -938,6 +983,15 @@ def start_callback_server() -> int:
             
             callback_server_running = True
             
+            # Set a timer to shutdown the server after CALLBACK_SERVER_TIMEOUT seconds
+            if server_shutdown_timer is not None:
+                server_shutdown_timer.cancel()
+            
+            server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
+            server_shutdown_timer.daemon = True
+            server_shutdown_timer.start()
+            print(f"Server will automatically shut down after {CALLBACK_SERVER_TIMEOUT} seconds of inactivity")
+            
             # Verify the server is actually accepting connections
             try:
                 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/meta_ads_mcp/core/pipeboard_auth.py

@@ -418,7 +418,7 @@ class PipeboardAuthManager:
             
         try:
             # Make a simple request to the /me endpoint to test the token
-            META_GRAPH_API_VERSION = "v20.0"
+            META_GRAPH_API_VERSION = "v22.0"
             url = f"https://graph.facebook.com/{META_GRAPH_API_VERSION}/me"
             headers = {"Authorization": f"Bearer {self.token_info.access_token}"}
             

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-ads-mcp"
-version = "0.3.0"
+version = "0.3.2"
 description = "Model Calling Protocol (MCP) plugin for interacting with Meta Ads API"
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [
-    {name = "Your Name", email = "your.email@example.com"},
+    {name = "Yves Junqueira", email = "yves.junqueira@gmail.com"},
 ]
 keywords = ["meta", "facebook", "ads", "api", "mcp", "claude"]
 license = {text = "MIT"}

meta_ads_mcp-0.3.2/smithery.yaml

@@ -0,0 +1,33 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      pipeboardApiToken:
+        type: string
+        description: "Pipeboard API token for Meta authentication (recommended). Get your free token at https://pipeboard.co"
+      metaAppId:
+        type: string
+        description: "Meta App ID (Client ID) for direct OAuth method (only needed if not using Pipeboard authentication)"
+    required: []
+  commandFunction: |
+    (config) => {
+      const env = {};
+      const args = ["-m", "meta_ads_mcp"];
+      
+      // Add Pipeboard API token to environment if provided (recommended auth method)
+      if (config.pipeboardApiToken) {
+        env.PIPEBOARD_API_TOKEN = config.pipeboardApiToken;
+      }
+      
+      // Add Meta App ID as command-line argument if provided (alternative auth method)
+      if (config.metaAppId) {
+        args.push("--app-id", config.metaAppId);
+      }
+      
+      return {
+        command: 'python',
+        args: args,
+        env: env
+      };
+    } 

{meta_ads_mcp-0.3.0 → meta_ads_mcp-0.3.2}/test_pipeboard_auth.py

@@ -26,7 +26,7 @@ from meta_ads_mcp.core.pipeboard_auth import pipeboard_auth_manager, PIPEBOARD_A
 from meta_ads_mcp.api import get_ad_accounts
 
 # Define Meta Graph API base URL for testing access token directly
-META_GRAPH_API_VERSION = "v20.0"
+META_GRAPH_API_VERSION = "v22.0"
 META_GRAPH_API_BASE = f"https://graph.facebook.com/{META_GRAPH_API_VERSION}"
 
 def test_server_connectivity(server_url, port=3000):