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

meta_ads_mcp/core/server.py

@@ -4,9 +4,12 @@ from mcp.server.fastmcp import FastMCP
 import argparse
 import os
 import sys
+import webbrowser
 from .auth import login as login_auth
 from .resources import list_resources, get_resource
 from .utils import logger
+from .pipeboard_auth import pipeboard_auth_manager
+import time
 
 # Initialize FastMCP server
 mcp_server = FastMCP("meta-ads", use_consistent_tool_format=True)
@@ -78,7 +81,49 @@ def main():
     # Handle login command
     if args.login:
         login_cli()
-    else:
-        # Initialize and run the server
-        logger.info("Starting MCP server with stdio transport")
-        mcp_server.run(transport='stdio') 
+        return 0
+    
+    # Check for Pipeboard authentication and token
+    pipeboard_api_token = os.environ.get("PIPEBOARD_API_TOKEN")
+    if pipeboard_api_token:
+        logger.info("Using Pipeboard authentication")
+        # Check for existing token
+        token = pipeboard_auth_manager.get_access_token()
+        if not token:
+            logger.info("No valid Pipeboard token found. Initiating browser-based authentication flow.")
+            print("No valid Meta token found. Opening browser for authentication...")
+            try:
+                # Initialize the auth flow and get the login URL
+                auth_data = pipeboard_auth_manager.initiate_auth_flow()
+                login_url = auth_data.get('loginUrl')
+                if login_url:
+                    logger.info(f"Opening browser with login URL: {login_url}")
+                    webbrowser.open(login_url)
+                    print("Please authorize the application in your browser.")
+                    print("After authorization, the token will be automatically retrieved.")
+                    print("Waiting for authentication to complete...")
+                    
+                    # Poll for token completion
+                    max_attempts = 30  # Try for 30 * 2 = 60 seconds
+                    for attempt in range(max_attempts):
+                        print(f"Waiting for authentication... ({attempt+1}/{max_attempts})")
+                        # Try to get the token again
+                        token = pipeboard_auth_manager.get_access_token(force_refresh=True)
+                        if token:
+                            print("Authentication successful!")
+                            break
+                        time.sleep(2)  # Wait 2 seconds between attempts
+                    
+                    if not token:
+                        print("Authentication timed out. Starting server anyway.")
+                        print("You may need to restart the server after completing authentication.")
+                else:
+                    logger.error("No login URL received from Pipeboard API")
+                    print("Error: Could not get authentication URL. Check your API token.")
+            except Exception as e:
+                logger.error(f"Error initiating browser-based authentication: {e}")
+                print(f"Error: Could not start authentication: {e}")
+    
+    # Initialize and run the server
+    logger.info("Starting MCP server with stdio transport")
+    mcp_server.run(transport='stdio') 

meta_ads_mcp/core/utils.py

@@ -17,11 +17,16 @@ import platform
 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.")
+# Only show warnings about Meta credentials if we're not using Pipeboard
+# Check for Pipeboard token in environment
+using_pipeboard = bool(os.environ.get("PIPEBOARD_API_TOKEN", ""))
+
+# Print warning if Meta app credentials are not configured and not using Pipeboard
+if not using_pipeboard:
+    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():
@@ -55,6 +60,7 @@ def setup_logging():
     # Log startup information
     logger.info(f"Logging initialized. Log file: {log_file}")
     logger.info(f"Platform: {platform.system()} {platform.release()}")
+    logger.info(f"Using Pipeboard authentication: {using_pipeboard}")
     
     return logger
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.2.6
+Version: 0.2.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
@@ -15,6 +15,7 @@ Requires-Dist: httpx>=0.26.0
 Requires-Dist: mcp[cli]>=1.6.0
 Requires-Dist: pathlib>=1.0.1
 Requires-Dist: pillow>=10.0.0
+Requires-Dist: python-dateutil>=2.8.2
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: requests>=2.32.3
 Description-Content-Type: text/markdown
@@ -49,6 +50,11 @@ 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
 uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
 ```
 
@@ -76,15 +82,50 @@ 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
+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:
+
+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
+   ```
+
+This method provides longer-lived tokens (60 days), simplified setup, and automatic token renewal.
+
 ### Usage with Claude in Cursor
 
 Add this to your `claude_desktop_config.json` to integrate with Claude in 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": {
@@ -228,6 +269,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor
 
 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
@@ -244,13 +286,47 @@ Before using the MCP server, you'll need to set up a Meta Developer App:
 
 ## Authentication
 
-The Meta Ads MCP uses the OAuth 2.0 flow designed for desktop apps. When authenticating, it will:
+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.
+
+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) first.
+
 ## Troubleshooting and Logging
 
 The Meta Ads MCP includes a comprehensive logging system to help troubleshoot issues:
@@ -265,21 +341,29 @@ Log files are stored in a platform-specific location:
 
 ### Common Issues
 
-#### App ID Issues
+#### Authentication Issues
 
-If you encounter errors like `(#200) Provide valid app ID`, check the following:
+If you're having authentication problems:
 
-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`
+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
 
-#### Authentication Errors
+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`
 
-Authentication errors can be tracked in the log file. Check for:
-- Token expiration issues
-- App permission problems
-- Connection errors
+#### 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
 
@@ -310,14 +394,15 @@ 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`
-   - macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
-   - Linux: `~/.config/meta-ads-mcp/token_cache.json`
+   - 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`
 
 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)
+   - `META_APP_ID`: Your Meta App ID (Client ID) - for direct OAuth method
+   - `PIPEBOARD_API_TOKEN`: Your Pipeboard API token - for Pipeboard authentication method
 
 ## Testing
 
@@ -339,11 +424,12 @@ 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. 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`
+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`
 
-These functions will automatically handle authentication if needed and provide a clickable login link.
+These functions will automatically handle authentication if needed and provide a clickable login link if required.
 
 ## Troubleshooting
 
@@ -352,20 +438,20 @@ These functions will automatically handle authentication if needed and provide a
 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
+   - 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)
    - 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 the command line:
+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:
    - 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. General authentication troubleshooting:
-   - Check that your app is properly configured in the Meta Developers portal
-   - Ensure your app has the necessary permissions (ads_management, ads_read, business_management)
-   - Verify the app's redirect URI includes `http://localhost:8888/callback`
-   - Try clearing the token cache (located in platform-specific directories listed in the Token Caching section)
-
 ### API Errors
 
 If you receive errors from the Meta API:

meta_ads_mcp-0.2.8.dist-info/RECORD

@@ -0,0 +1,21 @@
+meta_ads_mcp/__init__.py,sha256=uoDoht-lvXHE6xVXDhLKtnB4QltQVpDwU5styQ3VtVk,1236
+meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
+meta_ads_mcp/api.py,sha256=lSyyvvcqZ8sGcd0R9Vk2b_4zDANTiU_z6AojfL7v41s,81984
+meta_ads_mcp/core/__init__.py,sha256=6T8iqrQrw9VHhKtncLqYWyDk8jeSBPs79hs1CSu-fLU,952
+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=ae6mreRtigqS7TnSI0AQA7wOeZpjwcSJ6q2nKpl1e5Q,7598
+meta_ads_mcp/core/api.py,sha256=ZflFD9WWScuSqi9c9m8b_Ck8S1FSTGENd3sh9rL5HfY,14182
+meta_ads_mcp/core/auth.py,sha256=bWJ0sRhowuHzsTHUOZ67jaa-Pjfl46Pbs7igafpi5Xc,20644
+meta_ads_mcp/core/authentication.py,sha256=3AHSXslZdxyg0_s2253aQhpOeguMSu2cSYq4H_auywY,6485
+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/pipeboard_auth.py,sha256=hmd9f54fFWwQgf3QIlFhyTKBnK4RetVealh_LwhmFvE,22798
+meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
+meta_ads_mcp/core/server.py,sha256=5WofyJZGzeDhbGzLXPhQjT0XnZwo0syeK8TM_XnJo4Q,5507
+meta_ads_mcp/core/utils.py,sha256=EPmpBX3OZaTWRS_YuEk_PLLyLXj7DeR6Ks8WoaZ5JGQ,6366
+meta_ads_mcp-0.2.8.dist-info/METADATA,sha256=GpkZAczdJeBD3-4o2nr-WYbRbp17026oEoGcY2zYXMo,19316
+meta_ads_mcp-0.2.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.2.8.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.2.8.dist-info/RECORD,,

meta_ads_mcp-0.2.6.dist-info/RECORD

@@ -1,20 +0,0 @@
-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,,