meta-ads-mcp 0.2.0__tar.gz → 0.2.2__tar.gz

{meta_ads_mcp-0.2.0 → meta_ads_mcp-0.2.2}/.gitignore

@@ -10,3 +10,13 @@ wheels/
 .venv
 .cursor/rules/meta-ads-credentials.mdc
 .DS_Store
+
+# Development environment files
+.python-version
+poetry.lock
+uv.lock
+.uv.toml
+.cursor/
+
+# Generated content
+ad_creatives/

meta_ads_mcp-0.2.2/PKG-INFO

@@ -0,0 +1,329 @@
+Metadata-Version: 2.4
+Name: meta-ads-mcp
+Version: 0.2.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>
+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.2/README.md

@@ -0,0 +1,308 @@
+# 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__)
+```