Meta Ads MCP Service Module

A Model Context Protocol (MCP) endpoint tailored for comprehensive interaction with Meta Advertising APIs. Leverage an advanced language model to distill operational metrics, render ad creative materials, and formulate prescriptive guidance for optimizing advertising initiatives running on Facebook, Instagram, and ancillary Meta properties.

IMPORTANT NOTICE: This utility functions as an independently maintained, unauthorized third-party integration. It maintains no formal affiliation, endorsement, or partnership with Meta. Access is established strictly via Meta's publicly documented APIs, adhering to their stipulated terms of service. All references to Meta, Facebook, Instagram, and associated branding are the proprietary marks of their respective rights holders.

mcp-name: co.pipeboard/meta-ads-mcp

Community & Support Channels

Discord Server: Engage with the user community.
Technical Inquiry Email: Direct correspondence for support requests.

Navigational Index

🚀 Initializing Remote MCP Access (Recommended for Marketing Professionals)
Local Deployment (For Advanced Technical Personnel)
Core Capabilities
Configuration Parameters
Exposed MCP Functions
Software Licensing Terms
Data Safeguarding and Confidentiality
Connection Validation Procedures
Issue Resolution Guidance

Initializing Remote MCP Access (Recommended)

The swiftest and most dependable method to commence operations involves utilizing our 🚀 Hosted Meta Ads Remote MCP Service. This cloud-based architecture employs streamable HTTP transit for robust and scalable retrieval of Meta Ads data. Setup is minimal—simply link your account to initiate AI-driven analysis of your advertising portfolios.

For Users of Claude Pro/Max

Navigate to claude.ai/settings/integrations (Requires active Claude Pro or Max subscription).
Select "Add Integration" and input the following:
Designation: "Pipeboard Meta Ads" (or your preferred label).
Integration Endpoint: https://mcp.pipeboard.co/meta-ads-mcp
Activate "Connect" adjacent to the new integration, then proceed through the authentication sequence:
Log in to the Pipeboard service.
Authorize access to your designated Facebook Ads entity.

Analysis, insight generation, and campaign administration via Claude are now available.

For Cursor Users

Incorporate the subsequent configuration into your ~/.cursor/mcp.json file. After enabling the remote endpoint, click the "Needs login" prompt to finalize credentials linkage.

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://mcp.pipeboard.co/meta-ads-mcp"
    }
  }
}

For Other MCP Consumers

Employ the designated Remote MCP URI: https://mcp.pipeboard.co/meta-ads-mcp

📖 Comprehensive setup instructions for your specific AI client are available here

Local Deployment (For Advanced Technical Personnel)

Developers or users requiring deep customization may opt for local execution of the Meta Ads MCP server. Most marketing users should adhere to the Remote MCP instructions above! Detailed technical instructions for local integration are documented in our Local Installation Guide.

This module also natively supports streamable HTTP messaging, allowing deployment as a self-contained API endpoint for custom web applications. Consult Streamable HTTP Setup Guide for precise configuration steps.

Rapid Local Initialization

# Install using uvx (preferred method)
uvx meta-ads-mcp

# Establish your Pipeboard authentication key
export PIPEBOARD_API_TOKEN=your_pipeboard_token

# Integrate into your MCP client configuration

For exhaustive, step-by-step deployment protocols, credential management, diagnostics, and error resolution, refer to LOCAL_INSTALLATION.md.

Core Capabilities

LLM-Driven Performance Evaluation: Enable your preferred LLM to derive actionable intelligence from campaign performance statistics.
Strategic Prescriptions: Furnish recommendations supported by empirical data concerning budget allocation, audience targeting refinement, and creative asset enhancement.
Automated Surveillance: Configure any MCP-compliant LLM to continuously monitor key metrics and issue alerts upon significant deviations.
Expenditure Stream Optimization: Receive guidance on reallocating capital to ad sets demonstrating superior efficacy.
Creative Element Refinement: Obtain qualitative feedback on ad copy veracity, visual components, and explicit calls-to-action.
Versatile Creative Variation Testing: Simplified API endpoints for deploying both monolithic ads and complex A/B testing arrays across headlines/descriptions.
Advertising Structure Control: Issue directives to modify campaigns, ad sets, and individual advertisements (all structural modifications mandate explicit confirmation).
Multi-Platform Synchronization: Seamless operation across the entire Meta advertising ecosystem (Facebook, Instagram).
Universal LLM Compatibility: Fully interoperable with major MCP clients, including Claude Desktop, Cursor, Cherry Studio, and others.
Advanced Querying: A generalized retrieval function prioritizes searching associated advertising pages when the query explicitly references "page" or "pages."
Simplified Authorization: Streamlined OAuth handshake process for initial setup.
OS Agnostic: Native functionality across Windows, macOS, and Linux environments.

Configuration Parameters

Remote MCP (Preferred Path)

✨ Initiate setup for Remote MCP here – zero local technical prerequisites! Connect your Facebook Ads account instantly to empower AI analysis of your advertising activities.

Local Deployment (For Technical Operators)

Details regarding configuration files, authorization methods, and advanced deployment prerequisites are located in our Local Installation Guide.

Exposed MCP Functions

mcp_meta_ads_get_ad_accounts
Retrieves all ad entities accessible to the authenticated user.
Inputs:
- access_token (Optional): Direct Meta API authorization key (falls back to cached credential if omitted).
- user_id: Identifier for the Meta user, or use "me".
- limit: Cap on the number of accounts returned (Default: 200).
Output: A collection of accessible ad accounts with associated metadata.
mcp_meta_ads_get_account_info
Fetches comprehensive data for a designated advertising account.
Inputs:
- access_token (Optional): Direct Meta API authorization key.
- account_id: The specific Meta Ads account identifier (Format: act_XXXXXXXXX).
Output: Detailed attributes of the requested account.
mcp_meta_ads_get_account_pages
Lists Facebook Pages linked to a specified Meta Ads account.
Inputs:
- access_token (Optional): Direct Meta API authorization key.
- account_id: Meta Ads account ID or "me" to query the current user's pages.
Output: Enumeration of pages associated with the account, relevant for ad placement context.
mcp_meta_ads_get_campaigns
Retrieves campaign entities for an account, allowing status-based filtering.
Inputs:
- access_token (Optional): Direct Meta API authorization key.
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- limit: Maximum campaign entities to fetch (Default: 10).
- status_filter: Filter criterion (e.g., 'ACTIVE', 'PAUSED'; blank returns all).
Output: A subset of campaigns adhering to the specified criteria.
mcp_meta_ads_get_campaign_details
Fetches granular information regarding one specific campaign.
Inputs:
- access_token (Optional): Direct Meta API authorization key.
- campaign_id: The unique identifier for the campaign.
Output: Comprehensive data structure for the specified campaign.
mcp_meta_ads_create_campaign
Initiates the creation of a novel advertising campaign within an account.
Inputs:
- access_token (Optional): Direct Meta API authorization key.
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- name: The designated name for the new campaign.
- objective: The intended outcome (Outcome-based objectives mandatory):
- OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION.
Note: Legacy objectives like BRAND_AWARENESS or CONVERSIONS must be mapped to the current outcome-based equivalents to prevent API rejection. - status: Initial provisioning status (Default: PAUSED). - special_ad_categories: Array specifying any required regulatory categories. - daily_budget: Daily spending cap, denominated in account currency subunits (cents). - lifetime_budget: Total campaign spending cap, denominated in account currency subunits (cents). - bid_strategy: The mechanism governing bids (e.g., LOWEST_COST_WITHOUT_CAP). - Output: Confirmation detailing the newly provisioned campaign entity.
Example Payload Structure: json { "name": "Q1 - Product Launch - Visibility", "account_id": "act_123456789012345", "objective": "OUTCOME_AWARENESS", "special_ad_categories": [], "status": "PAUSED", "buying_type": "AUCTION", "bid_strategy": "LOWEST_COST_WITHOUT_CAP", "daily_budget": 10000 }
mcp_meta_ads_get_adsets
Retrieves ad set entities, optionally filtered by parent campaign.
Inputs:
- access_token (Optional): Direct Meta API authorization key.
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- limit: Maximum ad sets to fetch (Default: 10).
- campaign_id: Identifier to restrict results to a specific campaign.
Output: A collection of ad sets matching the criteria.
mcp_meta_ads_get_adset_details
Retrieves exhaustive data for a single ad set.
Inputs:
- access_token (Optional): Direct Meta API authorization key.
- adset_id: The unique identifier for the ad set.
Output: Detailed attribute report for the specified ad set.
mcp_meta_ads_create_adset
Provisions a new ad set under a specified campaign.
Inputs:
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- campaign_id: The container campaign identifier.
- name: The chosen name for the ad set.
- status: Initial operational state (Default: PAUSED).
- daily_budget: Daily expenditure ceiling (string representation of cents).
- lifetime_budget: Total expenditure ceiling (string representation of cents).
- targeting: Detailed parameters defining the audience composition.
- optimization_goal: Metric prioritized for optimization (e.g., 'LINK_CLICKS').
- billing_event: The trigger for billing (e.g., 'IMPRESSIONS').
- bid_amount: Specified maximum bid, in currency subunits (cents).
- bid_strategy: The governing bid methodology (e.g., 'LOWEST_COST').
- start_time, end_time: Optional temporal boundaries (ISO 8601 format).
- access_token (Optional): Meta API authorization key.
Output: Confirmation detailing the newly provisioned ad set structure.
mcp_meta_ads_get_ads
- Retrieves advertisement entities, filterable by campaign or ad set.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- limit: Maximum ads to return (Default: 10).
- campaign_id: Optional filter by parent campaign ID.
- adset_id: Optional filter by parent ad set ID.
- Output: List of advertisements satisfying the filtering constraints.
mcp_meta_ads_create_ad
- Establishes a new advertisement utilizing a pre-existing creative asset.
- Inputs:
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- name: The assigned name for the advertisement.
- adset_id: The identifier of the containing ad set.
- creative_id: Identifier of the material asset to employ.
- status: Initial publishing state (Default: PAUSED).
- bid_amount: Optional bid ceiling (in cents).
- tracking_specs: Configuration for impression/click tracking parameters.
- access_token (Optional): Meta API authorization key.
- Output: Confirmation detailing the newly instantiated advertisement.
mcp_meta_ads_get_ad_details
- Fetches granular details pertaining to a specific advertisement.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- ad_id: The unique Meta Ads advertisement identifier.
- Output: Complete attribute record for the specified ad.
mcp_meta_ads_get_ad_creatives
- Retrieves the composition details for an advertisement's creative asset.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- ad_id: The Meta Ads identifier for the advertisement.
- Output: Creative specifications including textual elements, visual references, and destination URLs.
mcp_meta_ads_create_ad_creative
- Generates a novel advertising creative, contingent upon a previously uploaded image hash.
- Inputs:
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- name: Label for the creative asset.
- image_hash: The unique identifier derived from the uploaded visual asset.
- page_id: The associated Facebook Page identity for the promotion.
- link_url: The canonical landing page address.
- message: The primary body text of the advertisement.
- headline: Single headline string (mutually exclusive with headlines).
- headlines: Array of headline strings for dynamic testing (mutually exclusive with headline).
- description: Single description string (mutually exclusive with descriptions).
- descriptions: Array of description strings for dynamic testing (mutually exclusive with description).
- dynamic_creative_spec: Configuration parameters for dynamic creative optimization.
- call_to_action_type: The selected button label type (e.g., 'LEARN_MORE').
- instagram_actor_id: Optional identifier for the linked Instagram profile.
- access_token (Optional): Meta API authorization key.
- Output: Confirmation data for the newly manufactured creative entity.
mcp_meta_ads_update_ad_creative
- Modifies existing creative content or configuration parameters.
- Inputs:
- creative_id: The Meta Ads identifier of the asset to revise.
- name: The new descriptive label for the creative.
- message: Revised body copy.
- headline: New singular headline (mutually exclusive with headlines).
- headlines: New array of headlines for variation testing (mutually exclusive with headline).
- description: New singular description (mutually exclusive with descriptions).
- descriptions: New array of descriptions for variation testing (mutually exclusive with description).
- dynamic_creative_spec: Updated settings for dynamic creative handling.
- call_to_action_type: The revised CTA button designation.
- access_token (Optional): Direct Meta API authorization key.
- Output: Confirmation payload reflecting the updated creative state.
mcp_meta_ads_upload_ad_image
- Transfers a local image file to the Meta Ads asset library for creative use.
- Inputs:
- account_id: Meta Ads account ID (Format: act_XXXXXXXXX).
- image_path: Local filesystem path pointing to the source image.
- name: Optional user-defined label for the uploaded file.
- access_token (Optional): Meta API authorization key.
- Output: JSON response containing the newly generated image hash and metadata.
mcp_meta_ads_get_ad_image
- Synchronously retrieves, decodes, and prepares an ad's associated visual asset for immediate LLM visual inspection.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- ad_id: Meta Ads identifier of the advertisement.
- Output: The ad image data formatted for direct visual analysis by the consuming agent.
mcp_meta_ads_update_ad
- Modifies operational parameters for an existing advertisement.
- Inputs:
- ad_id: Meta Ads identifier for the advertisement.
- status: Target status for the ad (e.g., ACTIVE, PAUSED).
- bid_amount: Revised bid limit, specified in currency subunits (cents for USD).
- access_token (Optional): Direct Meta API authorization key.
- Output: Confirmation of the modification, including a reference link for verification.
mcp_meta_ads_update_adset
- Revamps an ad set's configuration, including frequency capping directives.
- Inputs:
- adset_id: Meta Ads identifier for the ad set.
- frequency_control_specs: Array defining constraints on impression frequency.
- bid_strategy: The revised methodology for bid management (e.g., 'LOWEST_COST_WITH_BID_CAP').
- bid_amount: New bid ceiling in currency subunits (cents for USD).
- status: Target operational state (ACTIVE, PAUSED, etc.).
- targeting: Updated audience targeting parameters, including targeting_automation directives.
- access_token (Optional): Direct Meta API authorization key.
- Output: Confirmation of the ad set revision, along with a verification hyperlink.
mcp_meta_ads_get_insights
- Fetches performance telemetry for an account, campaign, ad set, or individual ad.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- object_id: The identifier of the entity whose metrics are requested.
- time_range: The duration for metric aggregation (Default: full available history).
- breakdown: Optional dimensional slicing for the data (e.g., age, gender, geographical locus).
- level: The hierarchical scope of aggregation (ad, adset, campaign, account).
- Output: The calculated performance metrics set for the specified object.
mcp_meta_ads_get_login_link
- Generates a functional URI required to initiate the Meta Ads authorization workflow.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- Output: A clickable resource link facilitating Meta credential linkage.
mcp_meta_ads_create_budget_schedule
- Establishes a time-bound budget modification schedule for a campaign.
- Inputs:
- campaign_id: Meta Ads campaign identifier.
- budget_value: The magnitude of the budget adjustment.
- budget_value_type: The nature of the adjustment ("ABSOLUTE" currency amount or "MULTIPLIER").
- time_start: Unix timestamp marking the schedule's commencement.
- time_end: Unix timestamp marking the schedule's conclusion.
- access_token (Optional): Meta API authorization key.
- Output: A JSON string containing the unique ID of the created schedule or an error notification.
mcp_meta_ads_search_interests
- Queries the Meta database to locate specific audience interest categories by keyword.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- query: The keyword used for interest lookup (e.g., "gardening", "digital art").
- limit: Maximum number of results to compile (Default: 25).
- Output: Interest records including ID, official name, estimated audience reach, and hierarchical path.
mcp_meta_ads_get_interest_suggestions
- Proposes related audience interests based on a provided list of existing interests.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- interest_list: An array of current interest names (e.g., ["Running", "Marathons"]).
- limit: Maximum number of recommendations to generate (Default: 25).
- Output: Suggested interests along with their identifiers, reach estimates, and descriptive annotations.
mcp_meta_ads_validate_interests
- Verifies the validity and audience size for a list of supplied interest names or IDs.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- interest_list: Names of interests to check (e.g., ["France", "Paris"]).
- interest_fbid_list: IDs of interests to check (e.g., ["6003700426513"]).
- Output: Validation outcomes confirming validity status and associated audience reach for each input element.
mcp_meta_ads_search_behaviors
- Fetches the complete directory of available behavioral targeting classification options.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- limit: Maximum number of records to retrieve (Default: 50).
- Output: Targeting options detailing ID, name, audience size boundaries, structural path, and description.
mcp_meta_ads_search_demographics
- Retrieves specific demographic targeting classifications.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- demographic_class: The category to query ('demographics', 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os').
- limit: Maximum number of records to retrieve (Default: 50).
- Output: Demographic options with ID, name, audience size range, path, and description.
mcp_meta_ads_search_geo_locations
- Conducts a search for valid geographic regions for targeting purposes.
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- query: Search string for the location (e.g., "Texas", "UK", "Berlin").
- location_types: Specifies the desired hierarchy level filter (e.g., ['country', 'city']).
- limit: Maximum number of locations to return (Default: 25).
- Output: Geographic data including system key, location name, type, and hierarchical structure context.
mcp_meta_ads_search (Augmented)
- Provides a generalized lookup across accounts, campaigns, ads, and associated advertising pages.
- Automatically triggers associated page lookups if the search term contains "page" or "pages".
- Inputs:
- access_token (Optional): Direct Meta API authorization key.
- query: The comprehensive search expression (e.g., "E-commerce Funnel ads", "Active Instagram pages").
- Output: A structured list of matching entity IDs, formatted for direct consumption by ChatGPT interfaces.

Software Licensing Terms

Meta Ads MCP is distributed under the Business Source License 1.1. This license permits:

✅ Gratuitous Usage for both individual and commercial operations.
✅ Full Flexibility to adapt and customize the source code.
✅ Freedom to Redistribute the modified or original package.
✅ Automatic Transition to fully open-source (Apache 2.0) status beginning January 1, 2029.

The sole prohibition is against offering this specific software as a distinct, hosted competitive service. Inquiries regarding alternative commercial licensing structures should be directed to us.

Data Safeguarding and Confidentiality

Meta Ads MCP adheres rigorously to established security protocols, featuring secure credential handling and automated authorization routines.

Remote MCP: All sensitive authorization artifacts are managed securely within the cloud environment; no local storage of tokens is necessary.
Local Deployment: Credentials are encrypted and persisted locally—consult the Local Installation Guide for specific security implementation specifics.

Connection Validation Procedures

Verify the operational status of your Meta Ads MCP deployment using any compatible MCP client:

Authorization Confirmation: Instruct your LLM to execute mcp_meta_ads_get_ad_accounts.
Account Data Sanity Check: Subsequently invoke mcp_meta_ads_get_account_info using a confirmed account identifier.
Campaign Retrieval Test: Attempt to list current advertising entities via mcp_meta_ads_get_campaigns.

For exhaustive validation procedures applicable to local installations, review the instructions within the Local Installation Guide.

Issue Resolution Guidance

💡 Simplest Remedy: Bypass Local Setup!

The most effective strategy for circumventing deployment complexities is to 🎯 transition to our Remote MCP service. This eliminates all installation and configuration overhead—simply link your advertising account and immediately begin leveraging AI-driven analytical capabilities.

Difficulties During Local Deployment

For exhaustive troubleshooting, diagnostic procedures, and resolution paths concerning local installation failures, refer to our Local Installation Guide, which comprehensively covers:

Authentication flow debugging.
Solutions for installation dependency conflicts.
Guidance on interpreting and resolving API error codes.
Commands for generating diagnostic logs.
Techniques for performance tuning.

meta-ads-mcp

Author

pipeboard-co

Quick Info

Actions

Tags