meta-ads-mcp 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

meta_ads_mcp/__init__.py

@@ -1,6 +1,6 @@
 """Meta Ads MCP - Model Calling Protocol plugin for Meta Ads API."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 # Import key functions to make them available at package level
 from .api import (

meta_ads_mcp-0.2.1.dist-info/METADATA

@@ -0,0 +1,329 @@
+Metadata-Version: 2.4
+Name: meta-ads-mcp
+Version: 0.2.1
+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>
+License: MIT
+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.11
+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-dotenv>=1.1.0
+Requires-Dist: requests>=2.32.3
+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.
+
+## 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
+
+## Installation
+
+### Using uv (recommended)
+
+When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
+
+```bash
+uvx meta-ads-mcp
+```
+
+If you want to install the package:
+
+```bash
+uv pip install meta-ads-mcp
+```
+
+For development (if you've cloned the repository):
+
+```bash
+# From the repository root
+uv pip install -e .
+```
+
+### Using pip
+
+Alternatively, you can install meta-ads-mcp via pip:
+
+```bash
+pip install meta-ads-mcp
+```
+
+After installation, you can run it as:
+
+```bash
+python -m meta_ads_mcp
+```
+
+## Configuration
+
+### 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"]
+  }
+}
+```
+
+### Available MCP Tools
+
+1. `mcp_meta_ads_get_ad_accounts`
+   - Get ad accounts accessible by a user
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `user_id`: Meta user ID or "me" for the current user
+     - `limit`: Maximum number of accounts to return (default: 10)
+   - Returns: List of accessible ad accounts with their details
+
+2. `mcp_meta_ads_get_account_info`
+   - Get detailed information about a specific ad account
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+   - Returns: Detailed information about the specified account
+
+3. `mcp_meta_ads_get_campaigns`
+   - Get campaigns for a Meta Ads account with optional filtering
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+     - `limit`: Maximum number of campaigns to return (default: 10)
+     - `status_filter`: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
+   - Returns: List of campaigns matching the criteria
+
+4. `mcp_meta_ads_get_campaign_details`
+   - Get detailed information about a specific campaign
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `campaign_id`: Meta Ads campaign ID
+   - Returns: Detailed information about the specified campaign
+
+5. `mcp_meta_ads_create_campaign`
+   - Create a new campaign in a Meta Ads account
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+     - `name`: Campaign name
+     - `objective`: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
+     - `status`: Initial campaign status (default: PAUSED)
+     - `special_ad_categories`: List of special ad categories if applicable
+     - `daily_budget`: Daily budget in account currency (in cents)
+     - `lifetime_budget`: Lifetime budget in account currency (in cents)
+   - Returns: Confirmation with new campaign details
+
+6. `mcp_meta_ads_get_adsets`
+   - Get ad sets for a Meta Ads account with optional filtering by campaign
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+     - `limit`: Maximum number of ad sets to return (default: 10)
+     - `campaign_id`: Optional campaign ID to filter by
+   - Returns: List of ad sets matching the criteria
+
+7. `mcp_meta_ads_get_adset_details`
+   - Get detailed information about a specific ad set
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `adset_id`: Meta Ads ad set ID
+   - Returns: Detailed information about the specified ad set
+
+8. `mcp_meta_ads_get_ads`
+   - Get ads for a Meta Ads account with optional filtering
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
+     - `limit`: Maximum number of ads to return (default: 10)
+     - `campaign_id`: Optional campaign ID to filter by
+     - `adset_id`: Optional ad set ID to filter by
+   - Returns: List of ads matching the criteria
+
+9. `mcp_meta_ads_get_ad_details`
+   - Get detailed information about a specific ad
+   - Inputs:
+     - `access_token` (optional): Meta API access token (will use cached token if not provided)
+     - `ad_id`: Meta Ads ad ID
+   - Returns: Detailed information about the specified ad
+
+10. `mcp_meta_ads_get_ad_creatives`
+    - Get creative details for a specific ad
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `ad_id`: Meta Ads ad ID
+    - Returns: Creative details including text, images, and URLs
+
+11. `mcp_meta_ads_get_ad_image`
+    - Get, download, and visualize a Meta ad image in one step
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `ad_id`: Meta Ads ad ID
+    - Returns: The ad image ready for direct visual analysis
+
+12. `mcp_meta_ads_get_insights`
+    - Get performance insights for a campaign, ad set, ad or account
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `object_id`: ID of the campaign, ad set, ad or account
+      - `time_range`: Time range for insights (default: maximum)
+      - `breakdown`: Optional breakdown dimension (e.g., age, gender, country)
+      - `level`: Level of aggregation (ad, adset, campaign, account)
+    - Returns: Performance metrics for the specified object
+
+13. `mcp_meta_ads_debug_image_download`
+    - Debug image download issues and report detailed diagnostics
+    - Inputs:
+      - `access_token` (optional): Meta API access token (will use cached token if not provided)
+      - `url`: Direct image URL to test (optional)
+      - `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`
+    - Get a clickable login link for Meta Ads authentication
+    - 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 uses the OAuth 2.0 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
+
+### Authentication Methods
+
+There are two ways to authenticate with the Meta Ads API:
+
+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.
+
+   ```
+   [Click here to authenticate with Meta Ads API](https://www.facebook.com/dialog/oauth?...)
+   ```
+
+   Just click the link, complete the authorization in your browser, and the token will be automatically captured and stored.
+
+2. **Command Line Authentication**
+
+   You can authenticate directly from the command line:
+
+   ```bash
+   uvx meta-ads-mcp --login --app-id YOUR_APP_ID
+   ```
+
+### Token Caching
+
+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 do not need to provide your access token for each command; it will be automatically retrieved from the cache.
+
+## Environment Variables
+
+You can set the following environment variables instead of passing them as arguments:
+
+- `META_APP_ID`: Your Meta App ID (Client ID)
+
+## 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.
+
+## 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 the command line:
+   - 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:
+
+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__)
+``` 

meta_ads_mcp-0.2.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+meta_ads_mcp/__init__.py,sha256=a8UpoSlu32NXZZyxCAXaXZ_o8Uo8UnrzPkqF1fSA4JA,665
+meta_ads_mcp/api.py,sha256=sahhuPeYSJN2uYjyDDXSd68MXD04gzcrTLn7wTs1A_0,74055
+meta_ads_mcp-0.2.1.dist-info/METADATA,sha256=qKyZfRYiesCRlaHg854-jRownsgfBrChv1pnmV1OYPg,12045
+meta_ads_mcp-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_mcp-0.2.1.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
+meta_ads_mcp-0.2.1.dist-info/RECORD,,

{meta_ads_mcp-0.2.0.dist-info → meta_ads_mcp-0.2.1.dist-info}/entry_points.txt

@@ -1,3 +1,2 @@
 [console_scripts]
-meta-ads-login = meta_ads_mcp.api:login_cli
 meta-ads-mcp = meta_ads_mcp:entrypoint

meta_ads_mcp-0.2.0.dist-info/METADATA

@@ -1,250 +0,0 @@
-Metadata-Version: 2.4
-Name: meta-ads-mcp
-Version: 0.2.0
-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>
-License: MIT
-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.11
-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-dotenv>=1.1.0
-Requires-Dist: requests>=2.32.3
-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.
-
-## 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
-
-## Setup
-
-### 1. Create 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
-
-### 2. Install the Package
-
-#### Using uv (Recommended)
-
-Install directly from GitHub:
-
-```bash
-uv pip install git+https://github.com/nictuku/meta-ads-mcp.git
-```
-
-Or if you've cloned the repository:
-
-```bash
-# From the repository root
-uv pip install -e .
-```
-
-#### Using pip
-
-```bash
-pip install git+https://github.com/nictuku/meta-ads-mcp.git
-```
-
-### 3. Install Dependencies (If installing from source)
-
-```bash
-uv pip install -r requirements.txt
-```
-
-Or:
-
-```bash
-pip install -r requirements.txt
-```
-
-## Authentication
-
-The Meta Ads MCP uses the OAuth 2.0 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
-
-### Authentication Methods
-
-There are two ways to authenticate with the Meta Ads API:
-
-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.
-
-   ```
-   [Click here to authenticate with Meta Ads API](https://www.facebook.com/dialog/oauth?...)
-   ```
-
-   Just click the link, complete the authorization in your browser, and the token will be automatically captured and stored.
-
-2. **Command Line Authentication**
-
-   You can also initiate authentication directly from the command line:
-
-   ```bash
-   python meta_ads_generated.py --login --app-id YOUR_APP_ID
-   ```
-   
-   Or use the convenience scripts:
-   
-   ```bash
-   # On macOS/Linux
-   ./login.sh YOUR_APP_ID
-   
-   # On Windows
-   login.bat YOUR_APP_ID
-   ```
-
-### Token Caching
-
-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 do not need to provide your access token for each command; it will be automatically retrieved from the cache.
-
-## Usage Examples
-
-### Test Authentication
-
-```bash
-python test_meta_ads_auth.py --app-id YOUR_APP_ID
-```
-
-### Get Ad Accounts
-
-```python
-import asyncio
-from meta_ads_mcp import get_ad_accounts
-
-async def main():
-    # Token will be automatically retrieved from cache
-    accounts_json = await get_ad_accounts()
-    print(accounts_json)
-
-asyncio.run(main())
-```
-
-### Get Campaign Details
-
-```python
-import asyncio
-from meta_ads_mcp import get_campaign_details
-
-async def main():
-    # Provide a campaign ID
-    campaign_details = await get_campaign_details(campaign_id="123456789")
-    print(campaign_details)
-
-asyncio.run(main())
-```
-
-### Create a Campaign
-
-```python
-import asyncio
-from meta_ads_mcp import create_campaign
-
-async def main():
-    result = await create_campaign(
-        account_id="act_123456789",
-        name="Test Campaign via MCP",
-        objective="AWARENESS",
-        status="PAUSED",
-        daily_budget=1000  # $10.00
-    )
-    print(result)
-
-asyncio.run(main())
-```
-
-## Environment Variables
-
-You can set the following environment variables instead of passing them as arguments:
-
-- `META_APP_ID`: Your Meta App ID (Client ID)
-
-## 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 `get_login_link` tool
-2. Verify account access by calling `get_ad_accounts`
-3. Check specific account details with `get_account_info`
-
-These functions will automatically handle authentication if needed and provide a clickable login link.
-
-## Troubleshooting
-
-### Authentication Issues
-
-If you encounter authentication issues:
-
-1. When using the LLM interface:
-   - Use the `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 the command line:
-   - Run with `--force-login` to get a fresh token: `python meta_ads_generated.py --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:
-
-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
-
-## Files
-
-This repository contains the implementation for the Meta Ads Marketing API Client Protocol (MCP).
-
-- `meta_ads_generated.py`: The main MCP implementation for Meta Ads API 

meta_ads_mcp-0.2.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-meta_ads_mcp/__init__.py,sha256=jomVG4lxzzyJr3h37_LVXTsDd1Ns1cFS0PTrE7BcX_E,665
-meta_ads_mcp/api.py,sha256=sahhuPeYSJN2uYjyDDXSd68MXD04gzcrTLn7wTs1A_0,74055
-meta_ads_mcp-0.2.0.dist-info/METADATA,sha256=vmtA_U-AKJT3DmJLl54cmVECD5ASyZ-j4PhP9SwT0R8,7021
-meta_ads_mcp-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meta_ads_mcp-0.2.0.dist-info/entry_points.txt,sha256=OlQx7CAcFINhkiShvxT0ng-NlQK2vx7qGTJ1gulyC-w,101
-meta_ads_mcp-0.2.0.dist-info/RECORD,,