A Model Context Protocol (MCP) server for interacting with Meta Ads. Analyze, manage and optimize Meta advertising campaigns through an AI interface. Use an LLM to retrieve performance data, visualize ad creatives, and provide strategic insights for your ads on Facebook, Instagram, and other Meta platforms. mcp-name: co.pipeboard/meta-ads-mcp - Discord. Join the community. - Email Support. Email u
Add this skill
npx mdskills install pipeboard-co/meta-ads-mcpComprehensive Meta Ads MCP with excellent tool coverage and clear setup paths for both cloud and local deployment
1# Meta Ads MCP23A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with Meta Ads. Analyze, manage and optimize Meta advertising campaigns through an AI interface. Use an LLM to retrieve performance data, visualize ad creatives, and provide strategic insights for your ads on Facebook, Instagram, and other Meta platforms.45> **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.67[](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)89[](https://lobehub.com/mcp/nictuku-meta-ads-mcp)1011mcp-name: co.pipeboard/meta-ads-mcp1213## Community & Support1415- [Discord](https://discord.gg/YzMwQ8zrjr). Join the community.16- [Email Support](mailto:info@pipeboard.co). Email us for support.1718## Table of Contents1920- [๐ Getting started with Remote MCP (Recommended for Marketers)](#getting-started-with-remote-mcp-recommended)21- [Local Installation (Technical Users Only)](#local-installation-technical-users-only)22- [Features](#features)23- [Configuration](#configuration)24- [Available MCP Tools](#available-mcp-tools)25- [Licensing](#licensing)26- [Privacy and Security](#privacy-and-security)27- [Testing](#testing)28- [Troubleshooting](#troubleshooting)2930## Getting started with Remote MCP (Recommended)3132The fastest and most reliable way to get started is to **[๐ Get started with our Meta Ads Remote MCP](https://pipeboard.co)**. Our cloud service uses streamable HTTP transport for reliable, scalable access to Meta Ads data. No technical setup required - just connect and start analyzing your ad campaigns with AI!3334### For Claude Pro/Max Users35361. Go to [claude.ai/settings/integrations](https://claude.ai/settings/integrations) (requires Claude Pro or Max)372. Click "Add Integration" and enter:38 - **Name**: "Pipeboard Meta Ads" (or any name you prefer)39 - **Integration URL**: `https://mcp.pipeboard.co/meta-ads-mcp`403. Click "Connect" next to the integration and follow the prompts to:41 - Login to Pipeboard42 - Connect your Facebook Ads account4344That's it! You can now ask Claude to analyze your Meta ad campaigns, get performance insights, and manage your advertising.4546#### Advanced: Direct Token Authentication (Claude)4748For direct token-based authentication without the interactive flow, use this URL format when adding the integration:4950```51https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN52```5354Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).5556### For Cursor Users5758Add the following to your `~/.cursor/mcp.json`. Once you enable the remote MCP, click on "Needs login" to finish the login process.596061```json62{63 "mcpServers": {64 "meta-ads-remote": {65 "url": "https://mcp.pipeboard.co/meta-ads-mcp"66 }67 }68}69```7071#### Advanced: Direct Token Authentication (Cursor)7273If you prefer to authenticate without the interactive login flow, you can include your Pipeboard API token directly in the URL:7475```json76{77 "mcpServers": {78 "meta-ads-remote": {79 "url": "https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN"80 }81 }82}83```8485Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).8687### For Other MCP Clients8889Use the Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`9091**[๐ Get detailed setup instructions for your AI client here](https://pipeboard.co)**9293#### Advanced: Direct Token Authentication (OpenClaw and other clients)9495For MCP clients that support token-based authentication, you can append your Pipeboard API token to the URL:9697```98https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN99```100101This bypasses the interactive login flow and authenticates immediately. Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).102103## Local Installation (Advanced Technical Users Only)104105๐ **We strongly recommend using [Remote MCP](https://pipeboard.co) instead** - it's faster, more reliable, and requires no technical setup.106107Meta Ads MCP also supports a local streamable HTTP transport, allowing you to run it as a standalone HTTP API for web applications and custom integrations. See **[Streamable HTTP Setup Guide](STREAMABLE_HTTP_SETUP.md)** for complete instructions.108109## Features110111- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance112- **Strategic Recommendations**: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content113- **Automated Monitoring**: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes114- **Budget Optimization**: Get recommendations for reallocating budget to better-performing ad sets115- **Creative Improvement**: Receive feedback on ad copy, imagery, and calls-to-action116- **Dynamic Creative Testing**: Easy API for both simple ads (single headline/description) and advanced A/B testing (multiple headlines/descriptions)117- **Campaign Management**: Request changes to campaigns, ad sets, and ads (all changes require explicit confirmation)118- **Cross-Platform Integration**: Works with Facebook, Instagram, and all Meta ad platforms119- **Universal LLM Support**: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more120- **Enhanced Search**: Generic search function includes page searching when queries mention "page" or "pages"121- **Simple Authentication**: Easy setup with secure OAuth authentication122- **Cross-Platform Support**: Works on Windows, macOS, and Linux123124## Configuration125126### Remote MCP (Recommended)127128**[โจ Get started with Remote MCP here](https://pipeboard.co)** - no technical setup required! Just connect your Facebook Ads account and start asking AI to analyze your campaigns.129130### Local Installation (Advanced Technical Users)131132For advanced users who need to self-host, the package can be installed from source. Local installations require creating your own Meta Developer App. **We recommend using [Remote MCP](https://pipeboard.co) for a simpler experience.**133134### Available MCP Tools1351361. `mcp_meta_ads_get_ad_accounts`137 - Get ad accounts accessible by a user138 - Inputs:139 - `access_token` (optional): Meta API access token (will use cached token if not provided)140 - `user_id`: Meta user ID or "me" for the current user141 - `limit`: Maximum number of accounts to return (default: 200)142 - Returns: List of accessible ad accounts with their details1431442. `mcp_meta_ads_get_account_info`145 - Get detailed information about a specific ad account146 - Inputs:147 - `access_token` (optional): Meta API access token (will use cached token if not provided)148 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)149 - Returns: Detailed information about the specified account1501513. `mcp_meta_ads_get_account_pages`152 - Get pages associated with a Meta Ads account153 - Inputs:154 - `access_token` (optional): Meta API access token (will use cached token if not provided)155 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX) or "me" for the current user's pages156 - Returns: List of pages associated with the account, useful for ad creation and management1571584. `mcp_meta_ads_get_campaigns`159 - Get campaigns for a Meta Ads account with optional filtering160 - Inputs:161 - `access_token` (optional): Meta API access token (will use cached token if not provided)162 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)163 - `limit`: Maximum number of campaigns to return (default: 10)164 - `status_filter`: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)165 - Returns: List of campaigns matching the criteria1661675. `mcp_meta_ads_get_campaign_details`168 - Get detailed information about a specific campaign169 - Inputs:170 - `access_token` (optional): Meta API access token (will use cached token if not provided)171 - `campaign_id`: Meta Ads campaign ID172 - Returns: Detailed information about the specified campaign1731746. `mcp_meta_ads_create_campaign`175 - Create a new campaign in a Meta Ads account176 - Inputs:177 - `access_token` (optional): Meta API access token (will use cached token if not provided)178 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)179 - `name`: Campaign name180 - `objective`: Campaign objective (ODAX, outcome-based). Must be one of:181 - `OUTCOME_AWARENESS`182 - `OUTCOME_TRAFFIC`183 - `OUTCOME_ENGAGEMENT`184 - `OUTCOME_LEADS`185 - `OUTCOME_SALES`186 - `OUTCOME_APP_PROMOTION`187188 Note: Legacy objectives such as `BRAND_AWARENESS`, `LINK_CLICKS`, `CONVERSIONS`, `APP_INSTALLS`, etc. are no longer valid for new campaigns and will cause a 400 error. Use the outcome-based values above. Common mappings:189 - `BRAND_AWARENESS` โ `OUTCOME_AWARENESS`190 - `REACH` โ `OUTCOME_AWARENESS`191 - `LINK_CLICKS`, `TRAFFIC` โ `OUTCOME_TRAFFIC`192 - `POST_ENGAGEMENT`, `PAGE_LIKES`, `EVENT_RESPONSES`, `VIDEO_VIEWS` โ `OUTCOME_ENGAGEMENT`193 - `LEAD_GENERATION` โ `OUTCOME_LEADS`194 - `CONVERSIONS`, `CATALOG_SALES`, `MESSAGES` (sales-focused flows) โ `OUTCOME_SALES`195 - `APP_INSTALLS` โ `OUTCOME_APP_PROMOTION`196 - `status`: Initial campaign status (default: PAUSED)197 - `special_ad_categories`: List of special ad categories if applicable198 - `daily_budget`: Daily budget in account currency (in cents)199 - `lifetime_budget`: Lifetime budget in account currency (in cents)200 - `bid_strategy`: Bid strategy. Must be one of: `LOWEST_COST_WITHOUT_CAP`, `LOWEST_COST_WITH_BID_CAP`, `COST_CAP`, `LOWEST_COST_WITH_MIN_ROAS`.201 - Returns: Confirmation with new campaign details202203 - Example:204 ```json205 {206 "name": "2025 - Bedroom Furniture - Awareness",207 "account_id": "act_123456789012345",208 "objective": "OUTCOME_AWARENESS",209 "special_ad_categories": [],210 "status": "PAUSED",211 "buying_type": "AUCTION",212 "bid_strategy": "LOWEST_COST_WITHOUT_CAP",213 "daily_budget": 10000214 }215 ```2162177. `mcp_meta_ads_get_adsets`218 - Get ad sets for a Meta Ads account with optional filtering by campaign219 - Inputs:220 - `access_token` (optional): Meta API access token (will use cached token if not provided)221 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)222 - `limit`: Maximum number of ad sets to return (default: 10)223 - `campaign_id`: Optional campaign ID to filter by224 - Returns: List of ad sets matching the criteria2252268. `mcp_meta_ads_get_adset_details`227 - Get detailed information about a specific ad set228 - Inputs:229 - `access_token` (optional): Meta API access token (will use cached token if not provided)230 - `adset_id`: Meta Ads ad set ID231 - Returns: Detailed information about the specified ad set2322339. `mcp_meta_ads_create_adset`234 - Create a new ad set in a Meta Ads account235 - Inputs:236 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)237 - `campaign_id`: Meta Ads campaign ID this ad set belongs to238 - `name`: Ad set name239 - `status`: Initial ad set status (default: PAUSED)240 - `daily_budget`: Daily budget in account currency (in cents) as a string241 - `lifetime_budget`: Lifetime budget in account currency (in cents) as a string242 - `targeting`: Targeting specifications (e.g., age, location, interests)243 - `optimization_goal`: Conversion optimization goal (e.g., 'LINK_CLICKS')244 - `billing_event`: How you're charged (e.g., 'IMPRESSIONS')245 - `bid_amount`: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.246 - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_MIN_ROAS')247 - `bid_constraints`: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS (e.g., `{"roas_average_floor": 20000}`)248 - `start_time`, `end_time`: Optional start/end times (ISO 8601)249 - `access_token` (optional): Meta API access token250 - Returns: Confirmation with new ad set details25125210. `mcp_meta_ads_get_ads`253 - Get ads for a Meta Ads account with optional filtering254 - Inputs:255 - `access_token` (optional): Meta API access token (will use cached token if not provided)256 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)257 - `limit`: Maximum number of ads to return (default: 10)258 - `campaign_id`: Optional campaign ID to filter by259 - `adset_id`: Optional ad set ID to filter by260 - Returns: List of ads matching the criteria26126211. `mcp_meta_ads_create_ad`263 - Create a new ad with an existing creative264 - Inputs:265 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)266 - `name`: Ad name267 - `adset_id`: Ad set ID where this ad will be placed268 - `creative_id`: ID of an existing creative to use269 - `status`: Initial ad status (default: PAUSED)270 - `bid_amount`: Optional bid amount (in cents)271 - `tracking_specs`: Optional tracking specifications272 - `access_token` (optional): Meta API access token273 - Returns: Confirmation with new ad details27427512. `mcp_meta_ads_get_ad_details`276 - Get detailed information about a specific ad277 - Inputs:278 - `access_token` (optional): Meta API access token (will use cached token if not provided)279 - `ad_id`: Meta Ads ad ID280 - Returns: Detailed information about the specified ad28128213. `mcp_meta_ads_get_ad_creatives`283 - Get creative details for a specific ad284 - Inputs:285 - `access_token` (optional): Meta API access token (will use cached token if not provided)286 - `ad_id`: Meta Ads ad ID287 - Returns: Creative details including text, images, and URLs28828914. `mcp_meta_ads_create_ad_creative`290 - Create a new ad creative using an uploaded image hash291 - Inputs:292 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)293 - `name`: Creative name294 - `image_hash`: Hash of the uploaded image295 - `page_id`: Facebook Page ID for the ad296 - `link_url`: Destination URL297 - `message`: Ad copy/text298 - `headline`: Single headline for simple ads (cannot be used with headlines)299 - `headlines`: List of headlines for dynamic creative testing (cannot be used with headline)300 - `description`: Single description for simple ads (cannot be used with descriptions)301 - `descriptions`: List of descriptions for dynamic creative testing (cannot be used with description)302 - `dynamic_creative_spec`: Dynamic creative optimization settings303 - `call_to_action_type`: CTA button type (e.g., 'LEARN_MORE')304 - `instagram_actor_id`: Optional Instagram account ID305 - `access_token` (optional): Meta API access token306 - Returns: Confirmation with new creative details30730815. `mcp_meta_ads_update_ad_creative`309 - Update an existing ad creative with new content or settings310 - Inputs:311 - `creative_id`: Meta Ads creative ID to update312 - `name`: New creative name313 - `message`: New ad copy/text314 - `headline`: Single headline for simple ads (cannot be used with headlines)315 - `headlines`: New list of headlines for dynamic creative testing (cannot be used with headline)316 - `description`: Single description for simple ads (cannot be used with descriptions)317 - `descriptions`: New list of descriptions for dynamic creative testing (cannot be used with description)318 - `dynamic_creative_spec`: New dynamic creative optimization settings319 - `call_to_action_type`: New call to action button type320 - `access_token` (optional): Meta API access token (will use cached token if not provided)321 - Returns: Confirmation with updated creative details32232316. `mcp_meta_ads_upload_ad_image`324 - Upload an image to use in Meta Ads creatives325 - Inputs:326 - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)327 - `image_path`: Path to the image file to upload328 - `name`: Optional name for the image329 - `access_token` (optional): Meta API access token330 - Returns: JSON response with image details including hash33133217. `mcp_meta_ads_get_ad_image`333 - Get, download, and visualize a Meta ad image in one step334 - Inputs:335 - `access_token` (optional): Meta API access token (will use cached token if not provided)336 - `ad_id`: Meta Ads ad ID337 - Returns: The ad image ready for direct visual analysis33833918. `mcp_meta_ads_update_ad`340 - Update an ad with new settings341 - Inputs:342 - `ad_id`: Meta Ads ad ID343 - `status`: Update ad status (ACTIVE, PAUSED, etc.)344 - `bid_amount`: Bid amount in account currency (in cents for USD)345 - `access_token` (optional): Meta API access token (will use cached token if not provided)346 - Returns: Confirmation with updated ad details and a confirmation link34734819. `mcp_meta_ads_update_adset`349 - Update an ad set with new settings including frequency caps350 - Inputs:351 - `adset_id`: Meta Ads ad set ID352 - `frequency_control_specs`: List of frequency control specifications353 - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP', 'LOWEST_COST_WITH_MIN_ROAS')354 - `bid_amount`: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.355 - `bid_constraints`: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS (e.g., `{"roas_average_floor": 20000}`)356 - `status`: Update ad set status (ACTIVE, PAUSED, etc.)357 - `targeting`: Targeting specifications including targeting_automation358 - `access_token` (optional): Meta API access token (will use cached token if not provided)359 - Returns: Confirmation with updated ad set details and a confirmation link36036120. `mcp_meta_ads_get_insights`362 - Get performance insights for a campaign, ad set, ad or account363 - Inputs:364 - `access_token` (optional): Meta API access token (will use cached token if not provided)365 - `object_id`: ID of the campaign, ad set, ad or account366 - `time_range`: Time range for insights (default: maximum)367 - `breakdown`: Optional breakdown dimension (e.g., age, gender, country)368 - `level`: Level of aggregation (ad, adset, campaign, account)369 - `action_attribution_windows` (optional): List of attribution windows for conversion data (e.g., ["1d_click", "1d_view", "7d_click", "7d_view"]). When specified, actions and cost_per_action_type include additional fields for each window. The 'value' field always shows 7d_click attribution.370 - Returns: Performance metrics for the specified object37137221. `mcp_meta_ads_get_login_link`373 - Get a clickable login link for Meta Ads authentication374 - Inputs:375 - `access_token` (optional): Meta API access token (will use cached token if not provided)376 - Returns: A clickable resource link for Meta authentication37737822. `mcp_meta_ads_create_budget_schedule`379 - Create a budget schedule for a Meta Ads campaign380 - Inputs:381 - `campaign_id`: Meta Ads campaign ID382 - `budget_value`: Amount of budget increase383 - `budget_value_type`: Type of budget value ("ABSOLUTE" or "MULTIPLIER")384 - `time_start`: Unix timestamp for when the high demand period should start385 - `time_end`: Unix timestamp for when the high demand period should end386 - `access_token` (optional): Meta API access token387 - Returns: JSON string with the ID of the created budget schedule or an error message38838923. `mcp_meta_ads_search_interests`390 - Search for interest targeting options by keyword391 - Inputs:392 - `access_token` (optional): Meta API access token (will use cached token if not provided)393 - `query`: Search term for interests (e.g., "baseball", "cooking", "travel")394 - `limit`: Maximum number of results to return (default: 25)395 - Returns: Interest data with id, name, audience_size, and path fields39639724. `mcp_meta_ads_get_interest_suggestions`398 - Get interest suggestions based on existing interests399 - Inputs:400 - `access_token` (optional): Meta API access token (will use cached token if not provided)401 - `interest_list`: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])402 - `limit`: Maximum number of suggestions to return (default: 25)403 - Returns: Suggested interests with id, name, audience_size, and description fields40440525. `mcp_meta_ads_validate_interests`406 - Validate interest names or IDs for targeting407 - Inputs:408 - `access_token` (optional): Meta API access token (will use cached token if not provided)409 - `interest_list`: List of interest names to validate (e.g., ["Japan", "Basketball"])410 - `interest_fbid_list`: List of interest IDs to validate (e.g., ["6003700426513"])411 - Returns: Validation results showing valid status and audience_size for each interest41241326. `mcp_meta_ads_search_behaviors`414 - Get all available behavior targeting options415 - Inputs:416 - `access_token` (optional): Meta API access token (will use cached token if not provided)417 - `limit`: Maximum number of results to return (default: 50)418 - Returns: Behavior targeting options with id, name, audience_size bounds, path, and description41942027. `mcp_meta_ads_search_demographics`421 - Get demographic targeting options422 - Inputs:423 - `access_token` (optional): Meta API access token (will use cached token if not provided)424 - `demographic_class`: Type of demographics ('demographics', 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os')425 - `limit`: Maximum number of results to return (default: 50)426 - Returns: Demographic targeting options with id, name, audience_size bounds, path, and description42742828. `mcp_meta_ads_search_geo_locations`429 - Search for geographic targeting locations430 - Inputs:431 - `access_token` (optional): Meta API access token (will use cached token if not provided)432 - `query`: Search term for locations (e.g., "New York", "California", "Japan")433 - `location_types`: Types of locations to search (['country', 'region', 'city', 'zip', 'geo_market', 'electoral_district'])434 - `limit`: Maximum number of results to return (default: 25)435 - Returns: Location data with key, name, type, and geographic hierarchy information43643729. `mcp_meta_ads_search` (Enhanced)438 - Generic search across accounts, campaigns, ads, and pages439 - Automatically includes page searching when query mentions "page" or "pages"440 - Inputs:441 - `access_token` (optional): Meta API access token (will use cached token if not provided)442 - `query`: Search query string (e.g., "Injury Payouts pages", "active campaigns")443 - Returns: List of matching record IDs in ChatGPT-compatible format444445## Licensing446447Meta Ads MCP is licensed under the [Business Source License 1.1](LICENSE), which means:448449- โ **Free to use** for individual and business purposes450- โ **Modify and customize** as needed451- โ **Redistribute** to others452- โ **Becomes fully open source** (Apache 2.0) on January 1, 2029453454The only restriction is that you cannot offer this as a competing hosted service. For questions about commercial licensing, please contact us.455456## Privacy and Security457458Meta Ads MCP follows security best practices with secure token management and automatic authentication handling.459460- **Remote MCP**: All authentication is handled securely in the cloud - no local token storage required461- **Local Installation**: Tokens are cached securely on your local machine462463## Testing464465### Basic Testing466467Test your Meta Ads MCP connection with any MCP client:4684691. **Verify Account Access**: Ask your LLM to use `mcp_meta_ads_get_ad_accounts`4702. **Check Account Details**: Use `mcp_meta_ads_get_account_info` with your account ID4713. **List Campaigns**: Try `mcp_meta_ads_get_campaigns` to see your ad campaigns472473For detailed local installation testing, see the source repository.474475## Troubleshooting476477### ๐ก Quick Fix: Skip the Technical Setup!478479The easiest way to avoid any setup issues is to **[๐ฏ use our Remote MCP instead](https://pipeboard.co)**. No downloads, no configuration - just connect your ads account and start getting AI insights on your campaigns immediately!480481### Local Installation Issues482483For local installation issues, refer to the source repository. **For the easiest experience, we recommend using [Remote MCP](https://pipeboard.co) instead.**484
Full transparency โ inspect the skill content before installing.