# Meta Ads MCP
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with Meta Ads API. This tool enables AI models to access, analyze, and manage Meta advertising campaigns through a standardized interface, allowing LLMs to retrieve performance data, visualize ad creatives, and provide strategic insights for Facebook, Instagram, and other Meta platforms.
> **DISCLAIMER:** This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.
[](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)
## Community & Support
- [Discord](https://discord.gg/hNxpJcqM52). Join the community.
- [Email Support](info@pipeboard.co). Email us for support.
## Quick Start
### Option 1: Using Pipeboard (Easiest)
1. Sign-up to [Pipeboard](https://pipeboard.co) to authenticate with Meta
2. Get your Pipeboard token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens)
3. Add this configuration to your MCP client:
```json
"mcpServers": {
"meta-ads": {
"command": "uvx",
"args": ["meta-ads-mcp-local"],
"env": {
"PIPEBOARD_API_TOKEN": "your_pipeboard_token"
}
}
}
```
### Option 2: Using Your Own Meta App (With HTTPS Support)
1. Create a Meta Developer App (see [CUSTOM_META_APP.md](CUSTOM_META_APP.md))
2. Add both redirect URIs to your Facebook app:
- `https://localhost:8443/callback` (HTTPS - preferred)
- `http://localhost:8888/callback` (HTTP - fallback)
3. Add this configuration:
```json
"mcpServers": {
"meta-ads": {
"command": "uvx",
"args": ["meta-ads-mcp-local", "--app-id", "YOUR_META_APP_ID"],
"env": {
"META_APP_ID": "YOUR_META_APP_ID",
"META_APP_SECRET": "YOUR_META_APP_SECRET"
}
}
}
```
> **🔒 HTTPS Support**: This fork automatically uses HTTPS for OAuth callbacks, solving Facebook's redirect URI requirements. See [HTTPS_SETUP.md](HTTPS_SETUP.md) for details.
> **📦 Installation**: For local installation options, see [INSTALLATION.md](INSTALLATION.md).
## Features
- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance
- **Strategic Recommendations**: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content
- **Automated Monitoring**: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes
- **Budget Optimization**: Get recommendations for reallocating budget to better-performing ad sets
- **Creative Improvement**: Receive feedback on ad copy, imagery, and calls-to-action
- **Campaign Management**: Request changes to campaigns, ad sets, and ads (all changes require explicit confirmation)
- **Cross-Platform Integration**: Works with Facebook, Instagram, and all Meta ad platforms
- **Universal LLM Support**: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more
- **Simple Authentication**: Easy setup with secure OAuth authentication
- **Cross-Platform Support**: Works on Windows, macOS, and Linux
## Advanced Setup
### Development Installation
If you're contributing to the project or need to run it directly:
```bash
# From the repository root
uv pip install -e .
```
## Privacy and Security
The Meta Ads MCP follows security best practices:
1. Tokens are cached in a platform-specific secure location:
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
## Testing
### LLM Interface Testing
When using the Meta Ads MCP with an LLM interface (like Claude):
1. Ensure the PIPEBOARD_API_TOKEN environment variable is set
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
3. Check specific account details with `mcp_meta_ads_get_account_info`
## Troubleshooting
### Authentication Issues
If you encounter authentication issues:
1. Verify your Pipeboard setup:
- Check that `PIPEBOARD_API_TOKEN` is set correctly
- Verify your token in the Pipeboard dashboard
- Try forcing a new login: `python test_pipeboard_auth.py --force-login`
2. When using the LLM interface:
- Ensure the PIPEBOARD_API_TOKEN environment variable is set
- Check that the callback server is running properly
### API Errors
If you receive errors from the Meta API:
1. Ensure the user has appropriate permissions on the ad accounts
2. Check if there are rate limits or other restrictions
3. Verify your Pipeboard token hasn't expired
## Log Location
Log files are stored in a platform-specific location:
- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`
- **Windows**: `%APPDATA%\meta-ads-mcp\meta_ads_debug.log`
- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log`
## Configuration
### Pipeboard Authentication
The easiest way to use Meta Ads MCP is with Pipeboard authentication:
1. Sign up at [Pipeboard.co](https://pipeboard.co) and generate an API token
2. Set the environment variable:
```bash
export PIPEBOARD_API_TOKEN=your_pipeboard_token
```
3. Run meta-ads-mcp - it will handle authentication automatically
### Usage with Cursor or Claude Desktop
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" // Get your token at https://pipeboard.co
}
}
}
```
## Transports
Meta Ads MCP uses **stdio transport** by default, which works with MCP clients like Claude Desktop and Cursor. For web applications and direct HTTP API access, see [STREAMABLE_HTTP_SETUP.md](STREAMABLE_HTTP_SETUP.md) for streamable HTTP transport configuration.
### Available MCP Tools
1. `mcp_meta_ads_get_ad_accounts`
- 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_account_pages`
- Get pages associated with 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) or "me" for the current user's pages
- Returns: List of pages associated with the account, useful for ad creation and management
4. `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
5. `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
6. `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
7. `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
8. `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
9. `mcp_meta_ads_create_adset`
- Create a new ad set in a Meta Ads account
- Inputs:
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
- `campaign_id`: Meta Ads campaign ID this ad set belongs to
- `name`: Ad set name
- `status`: Initial ad set status (default: PAUSED)
- `daily_budget`: Daily budget in account currency (in cents) as a string
- `lifetime_budget`: Lifetime budget in account currency (in cents) as a string
- `targeting`: Targeting specifications (e.g., age, location, interests)
- `optimization_goal`: Conversion optimization goal (e.g., 'LINK_CLICKS')
- `billing_event`: How you're charged (e.g., 'IMPRESSIONS')
- `bid_amount`: Bid amount in account currency (in cents)
- `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST')
- `start_time`, `end_time`: Optional start/end times (ISO 8601)
- `access_token` (optional): Meta API access token
- Returns: Confirmation with new ad set details
10. `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
11. `mcp_meta_ads_create_ad`
- Create a new ad with an existing creative
- Inputs:
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
- `name`: Ad name
- `adset_id`: Ad set ID where this ad will be placed
- `creative_id`: ID of an existing creative to use
- `status`: Initial ad status (default: PAUSED)
- `bid_amount`: Optional bid amount (in cents)
- `tracking_specs`: Optional tracking specifications
- `access_token` (optional): Meta API access token
- Returns: Confirmation with new ad details
12. `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
13. `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
14. `mcp_meta_ads_create_ad_creative`
- Create a new ad creative using an uploaded image hash
- Inputs:
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
- `name`: Creative name
- `image_hash`: Hash of the uploaded image
- `page_id`: Facebook Page ID for the ad
- `link_url`: Destination URL
- `message`: Ad copy/text
- `headline`: Ad headline
- `description`: Ad description
- `call_to_action_type`: CTA button type (e.g., 'LEARN_MORE')
- `instagram_actor_id`: Optional Instagram account ID
- `access_token` (optional): Meta API access token
- Returns: Confirmation with new creative details
15. `mcp_meta_ads_upload_ad_image`
- Upload an image to use in Meta Ads creatives
- Inputs:
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
- `image_path`: Path to the image file to upload
- `name`: Optional name for the image
- `access_token` (optional): Meta API access token
- Returns: JSON response with image details including hash
16. `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
17. `mcp_meta_ads_update_ad`
- Update an ad with new settings
- Inputs:
- `ad_id`: Meta Ads ad ID
- `status`: Update ad status (ACTIVE, PAUSED, etc.)
- `bid_amount`: Bid amount in account currency (in cents for USD)
- `access_token` (optional): Meta API access token (will use cached token if not provided)
- Returns: Confirmation with updated ad details and a confirmation link
18. `mcp_meta_ads_update_adset`
- Update an ad set with new settings including frequency caps
- Inputs:
- `adset_id`: Meta Ads ad set ID
- `frequency_control_specs`: List of frequency control specifications
- `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP')
- `bid_amount`: Bid amount in account currency (in cents for USD)
- `status`: Update ad set status (ACTIVE, PAUSED, etc.)
- `targeting`: Targeting specifications including targeting_automation
- `access_token` (optional): Meta API access token (will use cached token if not provided)
- Returns: Confirmation with updated ad set details and a confirmation link
19. `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
20. `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
21. `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
22. `mcp_meta-ads_create_budget_schedule`
- Create a budget schedule for a Meta Ads campaign.
- Inputs:
- `campaign_id`: Meta Ads campaign ID.
- `budget_value`: Amount of budget increase.
- `budget_value_type`: Type of budget value ("ABSOLUTE" or "MULTIPLIER").
- `time_start`: Unix timestamp for when the high demand period should start.
- `time_end`: Unix timestamp for when the high demand period should end.
- `access_token` (optional): Meta API access token.
- Returns: JSON string with the ID of the created budget schedule or an error message.
Raw data
{
"_id": null,
"home_page": null,
"name": "meta-ads-mcp-local",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ads, api, claude, facebook, https, mcp, meta, oauth",
"author": null,
"author_email": "Yves Junqueira <yves.junqueira@gmail.com>, Fork Maintainer <fork@example.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/ae/bda1b5b101f4e71d3db9c806f34617b58039ed762f05035ca9e4ac89be17/meta_ads_mcp_local-0.4.5.tar.gz",
"platform": null,
"description": "# Meta Ads MCP\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with Meta Ads API. This tool enables AI models to access, analyze, and manage Meta advertising campaigns through a standardized interface, allowing LLMs to retrieve performance data, visualize ad creatives, and provide strategic insights for Facebook, Instagram, and other Meta platforms.\n\n> **DISCLAIMER:** This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.\n\n[](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)\n\n\n## Community & Support\n\n- [Discord](https://discord.gg/hNxpJcqM52). Join the community.\n- [Email Support](info@pipeboard.co). Email us for support.\n \n## Quick Start\n\n### Option 1: Using Pipeboard (Easiest)\n\n1. Sign-up to [Pipeboard](https://pipeboard.co) to authenticate with Meta\n2. Get your Pipeboard token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens) \n3. Add this configuration to your MCP client:\n\n```json\n\"mcpServers\": {\n \"meta-ads\": {\n \"command\": \"uvx\",\n \"args\": [\"meta-ads-mcp-local\"],\n \"env\": {\n \"PIPEBOARD_API_TOKEN\": \"your_pipeboard_token\"\n }\n }\n}\n```\n\n### Option 2: Using Your Own Meta App (With HTTPS Support)\n\n1. Create a Meta Developer App (see [CUSTOM_META_APP.md](CUSTOM_META_APP.md))\n2. Add both redirect URIs to your Facebook app:\n - `https://localhost:8443/callback` (HTTPS - preferred)\n - `http://localhost:8888/callback` (HTTP - fallback)\n3. Add this configuration:\n\n```json\n\"mcpServers\": {\n \"meta-ads\": {\n \"command\": \"uvx\", \n \"args\": [\"meta-ads-mcp-local\", \"--app-id\", \"YOUR_META_APP_ID\"],\n \"env\": {\n \"META_APP_ID\": \"YOUR_META_APP_ID\",\n \"META_APP_SECRET\": \"YOUR_META_APP_SECRET\"\n }\n }\n}\n```\n\n> **\ud83d\udd12 HTTPS Support**: This fork automatically uses HTTPS for OAuth callbacks, solving Facebook's redirect URI requirements. See [HTTPS_SETUP.md](HTTPS_SETUP.md) for details.\n\n> **\ud83d\udce6 Installation**: For local installation options, see [INSTALLATION.md](INSTALLATION.md).\n\n## Features\n\n- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance\n- **Strategic Recommendations**: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content\n- **Automated Monitoring**: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes\n- **Budget Optimization**: Get recommendations for reallocating budget to better-performing ad sets\n- **Creative Improvement**: Receive feedback on ad copy, imagery, and calls-to-action\n- **Campaign Management**: Request changes to campaigns, ad sets, and ads (all changes require explicit confirmation)\n- **Cross-Platform Integration**: Works with Facebook, Instagram, and all Meta ad platforms\n- **Universal LLM Support**: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more\n- **Simple Authentication**: Easy setup with secure OAuth authentication\n- **Cross-Platform Support**: Works on Windows, macOS, and Linux\n\n## Advanced Setup\n\n### Development Installation\n\nIf you're contributing to the project or need to run it directly:\n\n```bash\n# From the repository root\nuv pip install -e .\n```\n\n## Privacy and Security\n\nThe Meta Ads MCP follows security best practices:\n\n1. Tokens are cached in a platform-specific secure location:\n - Windows: `%APPDATA%\\meta-ads-mcp\\token_cache.json`\n - macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`\n - Linux: `~/.config/meta-ads-mcp/token_cache.json`\n\n2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.\n\n## Testing\n\n### LLM Interface Testing\n\nWhen using the Meta Ads MCP with an LLM interface (like Claude):\n\n1. Ensure the PIPEBOARD_API_TOKEN environment variable is set\n2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`\n3. Check specific account details with `mcp_meta_ads_get_account_info`\n\n## Troubleshooting\n\n### Authentication Issues\n\nIf you encounter authentication issues:\n\n1. Verify your Pipeboard setup:\n - Check that `PIPEBOARD_API_TOKEN` is set correctly\n - Verify your token in the Pipeboard dashboard\n - Try forcing a new login: `python test_pipeboard_auth.py --force-login`\n\n2. When using the LLM interface:\n - Ensure the PIPEBOARD_API_TOKEN environment variable is set\n - Check that the callback server is running properly\n\n### API Errors\n\nIf you receive errors from the Meta API:\n1. Ensure the user has appropriate permissions on the ad accounts\n2. Check if there are rate limits or other restrictions\n3. Verify your Pipeboard token hasn't expired\n\n## Log Location\n\nLog files are stored in a platform-specific location:\n\n- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`\n- **Windows**: `%APPDATA%\\meta-ads-mcp\\meta_ads_debug.log` \n- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log` \n\n## Configuration\n\n### Pipeboard Authentication\n\nThe easiest way to use Meta Ads MCP is with Pipeboard authentication:\n\n1. Sign up at [Pipeboard.co](https://pipeboard.co) and generate an API token\n2. Set the environment variable:\n ```bash\n export PIPEBOARD_API_TOKEN=your_pipeboard_token\n ```\n3. Run meta-ads-mcp - it will handle authentication automatically\n\n### Usage with Cursor or Claude Desktop\n\nAdd this to your `claude_desktop_config.json` to integrate with Claude or `~/.cursor/mcp.json` to integrate with Cursor:\n\n```json\n\"mcpServers\": {\n \"meta-ads\": {\n \"command\": \"uvx\",\n \"args\": [\"meta-ads-mcp\"],\n \"env\": {\n \"PIPEBOARD_API_TOKEN\": \"your_pipeboard_token\" // Get your token at https://pipeboard.co\n }\n }\n}\n```\n\n## Transports\n\nMeta Ads MCP uses **stdio transport** by default, which works with MCP clients like Claude Desktop and Cursor. For web applications and direct HTTP API access, see [STREAMABLE_HTTP_SETUP.md](STREAMABLE_HTTP_SETUP.md) for streamable HTTP transport configuration.\n\n### Available MCP Tools\n\n1. `mcp_meta_ads_get_ad_accounts`\n - Get ad accounts accessible by a user\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `user_id`: Meta user ID or \"me\" for the current user\n - `limit`: Maximum number of accounts to return (default: 10)\n - Returns: List of accessible ad accounts with their details\n\n2. `mcp_meta_ads_get_account_info`\n - Get detailed information about a specific ad account\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - Returns: Detailed information about the specified account\n\n3. `mcp_meta_ads_get_account_pages`\n - Get pages associated with a Meta Ads account\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX) or \"me\" for the current user's pages\n - Returns: List of pages associated with the account, useful for ad creation and management\n\n4. `mcp_meta_ads_get_campaigns`\n - Get campaigns for a Meta Ads account with optional filtering\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `limit`: Maximum number of campaigns to return (default: 10)\n - `status_filter`: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)\n - Returns: List of campaigns matching the criteria\n\n5. `mcp_meta_ads_get_campaign_details`\n - Get detailed information about a specific campaign\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `campaign_id`: Meta Ads campaign ID\n - Returns: Detailed information about the specified campaign\n\n6. `mcp_meta_ads_create_campaign`\n - Create a new campaign in a Meta Ads account\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `name`: Campaign name\n - `objective`: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)\n - `status`: Initial campaign status (default: PAUSED)\n - `special_ad_categories`: List of special ad categories if applicable\n - `daily_budget`: Daily budget in account currency (in cents)\n - `lifetime_budget`: Lifetime budget in account currency (in cents)\n - Returns: Confirmation with new campaign details\n\n7. `mcp_meta_ads_get_adsets`\n - Get ad sets for a Meta Ads account with optional filtering by campaign\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `limit`: Maximum number of ad sets to return (default: 10)\n - `campaign_id`: Optional campaign ID to filter by\n - Returns: List of ad sets matching the criteria\n\n8. `mcp_meta_ads_get_adset_details`\n - Get detailed information about a specific ad set\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `adset_id`: Meta Ads ad set ID\n - Returns: Detailed information about the specified ad set\n\n9. `mcp_meta_ads_create_adset`\n - Create a new ad set in a Meta Ads account\n - Inputs:\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `campaign_id`: Meta Ads campaign ID this ad set belongs to\n - `name`: Ad set name\n - `status`: Initial ad set status (default: PAUSED)\n - `daily_budget`: Daily budget in account currency (in cents) as a string\n - `lifetime_budget`: Lifetime budget in account currency (in cents) as a string\n - `targeting`: Targeting specifications (e.g., age, location, interests)\n - `optimization_goal`: Conversion optimization goal (e.g., 'LINK_CLICKS')\n - `billing_event`: How you're charged (e.g., 'IMPRESSIONS')\n - `bid_amount`: Bid amount in account currency (in cents)\n - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST')\n - `start_time`, `end_time`: Optional start/end times (ISO 8601)\n - `access_token` (optional): Meta API access token\n - Returns: Confirmation with new ad set details\n\n10. `mcp_meta_ads_get_ads`\n - Get ads for a Meta Ads account with optional filtering\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `limit`: Maximum number of ads to return (default: 10)\n - `campaign_id`: Optional campaign ID to filter by\n - `adset_id`: Optional ad set ID to filter by\n - Returns: List of ads matching the criteria\n\n11. `mcp_meta_ads_create_ad`\n - Create a new ad with an existing creative\n - Inputs:\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `name`: Ad name\n - `adset_id`: Ad set ID where this ad will be placed\n - `creative_id`: ID of an existing creative to use\n - `status`: Initial ad status (default: PAUSED)\n - `bid_amount`: Optional bid amount (in cents)\n - `tracking_specs`: Optional tracking specifications\n - `access_token` (optional): Meta API access token\n - Returns: Confirmation with new ad details\n\n12. `mcp_meta_ads_get_ad_details`\n - Get detailed information about a specific ad\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `ad_id`: Meta Ads ad ID\n - Returns: Detailed information about the specified ad\n\n13. `mcp_meta_ads_get_ad_creatives`\n - Get creative details for a specific ad\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `ad_id`: Meta Ads ad ID\n - Returns: Creative details including text, images, and URLs\n\n14. `mcp_meta_ads_create_ad_creative`\n - Create a new ad creative using an uploaded image hash\n - Inputs:\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `name`: Creative name\n - `image_hash`: Hash of the uploaded image\n - `page_id`: Facebook Page ID for the ad\n - `link_url`: Destination URL\n - `message`: Ad copy/text\n - `headline`: Ad headline\n - `description`: Ad description\n - `call_to_action_type`: CTA button type (e.g., 'LEARN_MORE')\n - `instagram_actor_id`: Optional Instagram account ID\n - `access_token` (optional): Meta API access token\n - Returns: Confirmation with new creative details\n\n15. `mcp_meta_ads_upload_ad_image`\n - Upload an image to use in Meta Ads creatives\n - Inputs:\n - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)\n - `image_path`: Path to the image file to upload\n - `name`: Optional name for the image\n - `access_token` (optional): Meta API access token\n - Returns: JSON response with image details including hash\n\n16. `mcp_meta_ads_get_ad_image`\n - Get, download, and visualize a Meta ad image in one step\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `ad_id`: Meta Ads ad ID\n - Returns: The ad image ready for direct visual analysis\n\n17. `mcp_meta_ads_update_ad`\n - Update an ad with new settings\n - Inputs:\n - `ad_id`: Meta Ads ad ID\n - `status`: Update ad status (ACTIVE, PAUSED, etc.)\n - `bid_amount`: Bid amount in account currency (in cents for USD)\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - Returns: Confirmation with updated ad details and a confirmation link\n\n18. `mcp_meta_ads_update_adset`\n - Update an ad set with new settings including frequency caps\n - Inputs:\n - `adset_id`: Meta Ads ad set ID\n - `frequency_control_specs`: List of frequency control specifications\n - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP')\n - `bid_amount`: Bid amount in account currency (in cents for USD)\n - `status`: Update ad set status (ACTIVE, PAUSED, etc.)\n - `targeting`: Targeting specifications including targeting_automation\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - Returns: Confirmation with updated ad set details and a confirmation link\n\n19. `mcp_meta_ads_get_insights`\n - Get performance insights for a campaign, ad set, ad or account\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `object_id`: ID of the campaign, ad set, ad or account\n - `time_range`: Time range for insights (default: maximum)\n - `breakdown`: Optional breakdown dimension (e.g., age, gender, country)\n - `level`: Level of aggregation (ad, adset, campaign, account)\n - Returns: Performance metrics for the specified object\n\n20. `mcp_meta_ads_debug_image_download`\n - Debug image download issues and report detailed diagnostics\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - `url`: Direct image URL to test (optional)\n - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)\n - Returns: Diagnostic information about image download attempts\n\n21. `mcp_meta_ads_get_login_link`\n - Get a clickable login link for Meta Ads authentication\n - Inputs:\n - `access_token` (optional): Meta API access token (will use cached token if not provided)\n - Returns: A clickable resource link for Meta authentication\n\n22. `mcp_meta-ads_create_budget_schedule`\n - Create a budget schedule for a Meta Ads campaign.\n - Inputs:\n - `campaign_id`: Meta Ads campaign ID.\n - `budget_value`: Amount of budget increase.\n - `budget_value_type`: Type of budget value (\"ABSOLUTE\" or \"MULTIPLIER\").\n - `time_start`: Unix timestamp for when the high demand period should start.\n - `time_end`: Unix timestamp for when the high demand period should end.\n - `access_token` (optional): Meta API access token.\n - Returns: JSON string with the ID of the created budget schedule or an error message.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Calling Protocol (MCP) plugin for interacting with Meta Ads API (Fork with HTTPS support)",
"version": "0.4.5",
"project_urls": {
"Bug Tracker": "https://github.com/nictuku/meta-ads-mcp/issues",
"Homepage": "https://github.com/nictuku/meta-ads-mcp"
},
"split_keywords": [
"ads",
" api",
" claude",
" facebook",
" https",
" mcp",
" meta",
" oauth"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "aecff95527460e8d1faed06fb9f88f0a0abba3965eeffa7b8a22d0604dc41f07",
"md5": "32a2e14cea1ca7d6083ab7c946f86ce0",
"sha256": "ba89a65910ad466dbdff344bd3547c8b155d01f339e5d6344fe27ec02e457214"
},
"downloads": -1,
"filename": "meta_ads_mcp_local-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32a2e14cea1ca7d6083ab7c946f86ce0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 73053,
"upload_time": "2025-08-05T23:39:49",
"upload_time_iso_8601": "2025-08-05T23:39:49.856949Z",
"url": "https://files.pythonhosted.org/packages/ae/cf/f95527460e8d1faed06fb9f88f0a0abba3965eeffa7b8a22d0604dc41f07/meta_ads_mcp_local-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4aaebda1b5b101f4e71d3db9c806f34617b58039ed762f05035ca9e4ac89be17",
"md5": "c466c76df302b7fa0a24213651d6291f",
"sha256": "d3523a98409f1b898e71fb732a482cb90bfe1745661441347113bd2ae7c22e7e"
},
"downloads": -1,
"filename": "meta_ads_mcp_local-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "c466c76df302b7fa0a24213651d6291f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 155530,
"upload_time": "2025-08-05T23:39:51",
"upload_time_iso_8601": "2025-08-05T23:39:51.303590Z",
"url": "https://files.pythonhosted.org/packages/4a/ae/bda1b5b101f4e71d3db9c806f34617b58039ed762f05035ca9e4ac89be17/meta_ads_mcp_local-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 23:39:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nictuku",
"github_project": "meta-ads-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "httpx",
"specs": [
[
">=",
"0.26.0"
]
]
},
{
"name": "mcp",
"specs": [
[
">=",
"1.10.1"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.32.3"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "pathlib",
"specs": [
[
">=",
"1.0.1"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
">=",
"2.8.2"
]
]
}
],
"lcname": "meta-ads-mcp-local"
}
JSON
