Meta Ad Performance Conduit (MCP)

A Model Context Protocol (MCP) implementation designed specifically for interacting with the advertising ecosystem managed by Meta. Leverage an advanced Language Model interface to dissect, govern, and optimize advertising initiatives running on Facebook, Instagram, and other Meta-owned channels. This system allows AI to access performance telemetry, render visual advertising material, and formulate data-driven strategic advice.

IMPORTANT NOTICE: This solution is an independent, third-party utility and possesses no formal affiliation, endorsement, or association with Meta Platforms, Inc. It is developed and maintained autonomously, utilizing Meta's publicly documented Application Programming Interfaces in strict adherence to their stipulated terms of service. All trademarks pertaining to Meta, Facebook, Instagram, and associated brands belong solely to their respective entities.

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

User Community & Support Channels

• Discord Server. Connect with other users and developers.
• Technical Assistance. Direct email contact for support inquiries.

Navigational Structure

• 🚀 Swift Start with Remote Conduit Access (Recommended for Marketing Professionals)
• Local Deployment (For Technical Implementers Only)
• Core Capabilities
• System Configuration Parameters
• Exposed MCP Operands
• Licensing Framework
• Data Privacy and Security Protocols
• Connectivity Verification Procedures
• Issue Resolution Guide

Swift Start with Remote Conduit Access (Recommended)

The quickest and most robust entry point is via our hosted 🚀 Meta Ads Remote MCP Service. This cloud-based architecture employs streamable HTTP communication for dependable, scalable retrieval of Meta Ad data. Zero local setup is required—simply link your account and commence sophisticated AI-driven analysis of your advertising inventories.

For Users of Claude Pro/Max Tiers

1. Navigate to claude.ai/settings/integrations (Subscription required).
2. Select "Add Integration" and populate the fields:
3. Identifier: "Pipeboard Meta Ads" (or a preferred alias)
4. Integration Endpoint: https://mcp.pipeboard.co/meta-ads-mcp
5. Initiate the "Connect" procedure adjacent to the new entry, which guides you through:
6. Authenticating with Pipeboard
7. Authorizing access to your designated Facebook Ads entity

Your AI assistant can now interpret Meta advertising outcomes, furnish performance intelligence, and assist with management tasks.

For Cursor Users

Incorporate the following configuration snippet into your ~/.cursor/mcp.json file. After enabling the remote MCP functionality, select "Needs login" to complete the credentialing phase.

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

For All Other MCP-Compliant Clients

Utilize the standardized Remote Conduit URL: https://mcp.pipeboard.co/meta-ads-mcp

📖 Access comprehensive installation documentation for your specific AI client here

Local Deployment (For Technical Implementers Only)

Developers or users requiring customization can execute the Meta Ads MCP environment directly on their hardware. Note: The vast majority of marketing personnel should opt for the Remote MCP solution described above! Consult our Local Installation Guide for exhaustive technical setup instructions.

Meta Ads MCP additionally supports streamable HTTP communication, enabling its use as an independent API endpoint for bespoke web applications and custom integrations. Review Streamable HTTP Setup Guide for deployment directives.

Expedited Local Initialization

bash

Install using uvx (preferred method)

uvx meta-ads-mcp

Define your Pipeboard authorization key

export PIPEBOARD_API_TOKEN=your_pipeboard_token

Integrate into your MCP client configuration

For detailed sequential procedures, authentication configuration, diagnostic routines, and common error resolutions, refer to LOCAL_INSTALLATION.md.

Core Capabilities

• LLM-Driven Performance Diagnostics: Enable your preferred Large Language Model to scrutinize campaign metrics and yield immediately applicable optimization recommendations.
• Strategic Optimization Directives: Receive suggestions substantiated by performance data regarding budget allocation, audience segmentation, and creative element refinement.
• Automated Metric Surveillance: Command any MCP-enabled LLM to continuously monitor key performance indicators and issue alerts upon significant deviation.
• Spend Reallocation Guidance: Propose optimal adjustments for distributing advertising funds towards superior-performing ad sets.
• Creative Element Enhancement: Obtain targeted critique on ad copy phrasing, visual assets, and call-to-action efficacy.
• Fluid Creative Iteration: Simplified interface for managing both static advertisements (fixed text/image) and sophisticated A/B/n testing variants (multiple textual options).
• Campaign Governance: Submit directives to modify campaign structures, ad sets, or individual ads (all modifications require explicit AI confirmation).
• Platform Interoperability: Seamless operation across advertising deployments on Facebook, Instagram, and all other Meta advertising surfaces.
• Universal AI Client Compatibility: Works flawlessly with all MCP-compliant interfaces, including Claude Desktop, Cursor, Cherry Studio, and more.
• Augmented Retrieval: A general search function that automatically prioritizes searching Meta Pages when the query explicitly references "page" or "pages."
• Streamlined Authorization: Simplified setup process leveraging secure OAuth flow.
• OS Agnostic Operation: Fully functional across Windows, macOS, and Linux operating systems.

System Configuration Parameters

Remote Conduit Access (Standard)

✨ Initiate setup via the Remote MCP portal here—no local technical configuration needed! Simply link your Facebook Ads entity and begin instructing the AI to analyze your advertising workflows.

Local Deployment (Technical Users)

For specifics on local environment configuration, authentication alternatives, and advanced deployment parameters, consult Local Installation Guide.

Exposed MCP Operands

1. mcp_meta_ads_get_ad_accounts
2. Retrieves the collection of advertising entities accessible to the authenticated user.
3. Inputs:
   • access_token (Optional): Token for Meta API access (defaults to cached token).
   • user_id: Identifier for the Meta user or use "me".
   • limit: Cap on the number of accounts returned (Default: 200).

4. Returns: A structured list detailing accessible ad accounts.

5. mcp_meta_ads_get_account_info

6. Fetches comprehensive metadata for a designated advertising account.
7. Inputs:
   • access_token (Optional): Token for Meta API access.
   • account_id: The specific Meta Ads account identifier (e.g., act_XXXXXXXXX).

8. Returns: Full details pertaining to the requested account.

9. mcp_meta_ads_get_account_pages

10. Lists the Facebook Pages linked to a specific Meta Ads entity.
11. Inputs:
    • access_token (Optional): Token for Meta API access.
    • account_id: The Meta Ads account ID or "me" to query the current user's pages.

12. Returns: An enumeration of associated pages, vital for ad creation context.

13. mcp_meta_ads_get_campaigns

14. Queries active and inactive advertising campaigns for an account, supporting filtering.
15. Inputs:
    • access_token (Optional): Token for Meta API access.
    • account_id: The Meta Ads account identifier (e.g., act_XXXXXXXXX).
    • limit: Maximum number of campaigns to fetch (Default: 10).
    • status_filter: Status criteria for exclusion/inclusion (e.g., 'ACTIVE', 'PAUSED').

16. Returns: A dataset of campaigns matching the specified criteria.

17. mcp_meta_ads_get_campaign_details

18. Retrieves in-depth configuration and status data for a singular campaign.
19. Inputs:
    • access_token (Optional): Token for Meta API access.
    • campaign_id: The unique identifier for the Meta Ads campaign.

20. Returns: Detailed structured data for the specified campaign.

21. mcp_meta_ads_create_campaign

22. Initiates the creation of a novel advertising campaign within a specified Meta Ads structure.
23. Inputs:
    • access_token (Optional): Token for Meta API access.
    • account_id: The destination Meta Ads account ID (e.g., act_XXXXXXXXX).
    • name: The designated nomenclature for the new campaign.
    • objective: The marketing goal, strictly using outcome-based values (e.g., OUTCOME_AWARENESS, OUTCOME_SALES). Legacy objectives will result in rejection.
    • status: Initial operational state (Default: PAUSED).
    • special_ad_categories: Array specifying regulatory categories, if relevant.
    • daily_budget: Daily financial limit, denominated in the account's currency (expressed in cents).
    • lifetime_budget: Total financial limit for the campaign duration (expressed in cents).
    • bid_strategy: The primary cost control mechanism to employ (e.g., LOWEST_COST_WITHOUT_CAP).

24. Returns: A confirmation payload detailing the newly provisioned campaign structure.

25. Example for an Awareness Goal:

    { "name": "Q1-2025 - Product X 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 }

26. mcp_meta_ads_get_adsets

27. Fetches the collection of ad sets tied to an account, optionally filtered by parent campaign.
28. Inputs:
    • access_token (Optional): Token for Meta API access.
    • account_id: The Meta Ads account identifier (e.g., act_XXXXXXXXX).
    • limit: Maximum number of ad sets retrieved (Default: 10).
    • campaign_id: Optional filter parameter to constrain results to one campaign.

29. Returns: A list of ad set records conforming to the criteria.

30. mcp_meta_ads_get_adset_details

31. Acquires granular configuration details for a particular ad set entity.
32. Inputs:
    • access_token (Optional): Token for Meta API access.
    • adset_id: The unique identifier for the Meta Ads ad set.

33. Returns: Comprehensive descriptive data for the specified ad set.

34. mcp_meta_ads_create_adset

35. Establishes a new ad set container within an existing Meta Ads framework.
36. Inputs:
    • account_id: The destination Meta Ads account ID (e.g., act_XXXXXXXXX).
    • campaign_id: The ID of the parent campaign.
    • name: The assigned identifier for the new ad set.
    • status: Initial operational state (Default: PAUSED).
    • daily_budget: Daily financial ceiling (string representation of cents).
    • lifetime_budget: Total campaign duration budget (string representation of cents).
    • targeting: Structured data defining audience parameters (e.g., geography, demographics).
    • optimization_goal: Metric targeted for conversion success (e.g., 'LINK_CLICKS').
    • billing_event: The action triggering a charge (e.g., 'IMPRESSIONS').
    • bid_amount: Target bid value (in cents).
    • bid_strategy: Chosen cost control method (e.g., 'LOWEST_COST').
    • start_time, end_time: Optional ISO 8601 timestamps for scheduling.
    • access_token (Optional): Meta API access token.

37. Returns: A confirmation payload detailing the newly established ad set.

38. mcp_meta_ads_get_ads

    • Retrieves advertising units associated with an account, filterable by campaign or ad set.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • account_id: The Meta Ads account identifier (e.g., act_XXXXXXXXX).
    • limit: Maximum number of ads returned (Default: 10).
    • campaign_id: Optional constraint to a specific campaign.
    • adset_id: Optional constraint to a specific ad set.
    • Returns: A dataset of ad records meeting the specified criteria.

39. mcp_meta_ads_create_ad

    • Provisions a new advertisement unit utilizing an already defined creative asset.
    • Inputs:
    • account_id: The Meta Ads account ID (e.g., act_XXXXXXXXX).
    • name: The label for the new advertisement.
    • adset_id: The ID of the parent ad set.
    • creative_id: The identifier for the asset to be displayed.
    • status: Initial posting status (Default: PAUSED).
    • bid_amount: Optional bid adjustment (in cents).
    • tracking_specs: Supplementary tracking configurations.
    • access_token (Optional): Meta API access token.
    • Returns: Confirmation detailing the newly instantiated ad structure.

40. mcp_meta_ads_get_ad_details

    • Fetches the complete configuration manifest for an individual advertisement.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • ad_id: The unique identifier for the Meta Ads unit.
    • Returns: Detailed configuration object for the specified ad.

41. mcp_meta_ads_get_ad_creatives

    • Retrieves the specific creative assets (text, imagery links, destinations) linked to a given advertisement.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • ad_id: The Meta Ads advertisement identifier.
    • Returns: The underlying creative assets payload.

42. mcp_meta_ads_create_ad_creative

    • Registers a new creative element, requiring a pre-uploaded image hash.
    • Inputs:
    • account_id: The Meta Ads account ID (e.g., act_XXXXXXXXX).
    • name: Nomenclature for the creative asset.
    • image_hash: Unique identifier generated upon image upload.
    • page_id: The Facebook Page associated with the advertisement.
    • link_url: The specified landing page URL.
    • message: Primary body text of the ad.
    • headline: Singular primary headline (exclusive with headlines).
    • headlines: Array of headlines for dynamic testing (exclusive with headline).
    • description: Singular explanatory text (exclusive with descriptions).
    • descriptions: Array of descriptive texts for dynamic testing (exclusive with description).
    • dynamic_creative_spec: JSON object defining dynamic optimization parameters.
    • call_to_action_type: The designated button label (e.g., 'LEARN_MORE').
    • instagram_actor_id: Optional Instagram entity identifier.
    • access_token (Optional): Meta API access token.
    • Returns: A success notification containing the generated creative entity ID.

43. mcp_meta_ads_update_ad_creative

    • Modifies the textual or asset configuration of an existing creative entity.
    • Inputs:
    • creative_id: The identifier of the creative asset to be modified.
    • name: New label for the creative.
    • message: Revised primary advertisement copy.
    • headline: New singular headline (mutually exclusive).
    • headlines: New array of headlines for variation testing (mutually exclusive).
    • description: New singular description field (mutually exclusive).
    • descriptions: New array of description variants (mutually exclusive).
    • dynamic_creative_spec: Updated parameters for dynamic creative optimization.
    • call_to_action_type: New designation for the CTA button.
    • access_token (Optional): Token for Meta API access.
    • Returns: Confirmation of the updated creative configuration.

44. mcp_meta_ads_upload_ad_image

    • Uploads a binary image file to Meta's servers for subsequent use in creatives.
    • Inputs:
    • account_id: The Meta Ads account ID (e.g., act_XXXXXXXXX).
    • image_path: Local filesystem path to the source image file.
    • name: Optional descriptive label for the uploaded file.
    • access_token (Optional): Meta API access token.
    • Returns: The server response object, including the crucial image hash.

45. mcp_meta_ads_get_ad_image

    • Retrieves, downloads, and prepares a specific ad image for direct visual analysis by the LLM.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • ad_id: The identifier of the associated advertisement.
    • Returns: The binary image data formatted for immediate visual inspection.

46. mcp_meta_ads_update_ad

    • Modifies operational parameters of an existing advertisement unit.
    • Inputs:
    • ad_id: The Meta Ads advertisement identifier.
    • status: Desired operational state (e.g., 'ACTIVE', 'PAUSED').
    • bid_amount: Revised bid floor (in cents, USD equivalent).
    • access_token (Optional): Token for Meta API access.
    • Returns: Confirmation detailing the updated ad settings, often including a direct link for manual review.

47. mcp_meta_ads_update_adset

    • Adjusts settings for an ad set, including frequency constraints.
    • Inputs:
    • adset_id: The Meta Ads ad set identifier.
    • frequency_control_specs: Array specifying impression frequency caps.
    • bid_strategy: The desired cost control methodology to adopt.
    • bid_amount: Revised bid value (in cents, USD equivalent).
    • status: Desired operational state (e.g., 'ACTIVE', 'PAUSED').
    • targeting: Updated audience parameters, potentially including targeting_automation directives.
    • access_token (Optional): Token for Meta API access.
    • Returns: Confirmation of updated ad set parameters, potentially with a link for external verification.

48. mcp_meta_ads_get_insights

    • Retrieves historical performance statistics aggregated at the campaign, ad set, ad, or account level.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • object_id: The ID of the entity whose data is required.
    • time_range: Specification for the data lookback period (Default: Full available history).
    • breakdown: Optional dimensional categorization for metric partitioning (e.g., gender, geography).
    • level: The aggregation hierarchy ('ad', 'adset', 'campaign', 'account').
    • Returns: Performance metrics dataset relevant to the specified entity and time window.

49. mcp_meta_ads_get_login_link

    • Generates a secure, disposable URI required to initiate the Meta Ads OAuth authorization process.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • Returns: A functional, clickable URI resource for credential setup.

50. mcp_meta_ads_create_budget_schedule

    • Defines a dynamic budget alteration schedule for a campaign, usually for peak demand periods.
    • Inputs:
    • campaign_id: The target Meta Ads campaign ID.
    • budget_value: The magnitude of budget adjustment.
    • budget_value_type: Specifies if the change is an absolute figure or a multiplier ('ABSOLUTE' or 'MULTIPLIER').
    • time_start: Unix epoch time marking the schedule commencement.
    • time_end: Unix epoch time marking the schedule conclusion.
    • access_token (Optional): Meta API access token.
    • Returns: A JSON message confirming the creation of the schedule ID or an error notice.

51. mcp_meta_ads_search_interests

    • Searches the Meta interest database based on a keyword query.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • query: The textual term to search for (e.g., "automotive", "yoga").
    • limit: Maximum number of relevant interests to return (Default: 25).
    • Returns: Data records for matching interests, including ID, name, estimated audience size, and structural path.

52. mcp_meta_ads_get_interest_suggestions

    • Recommends related audience interests based on a seed list.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • interest_list: Names of interests to derive suggestions from (e.g., ["Gardening"]).
    • limit: Cap on the number of suggestions provided (Default: 25).
    • Returns: A list of suggested interests, including identifiers, names, audience estimates, and descriptions.

53. mcp_meta_ads_validate_interests

    • Confirms the validity and current audience scope of specified interest names or IDs.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • interest_list: List of interest names to verify.
    • interest_fbid_list: List of corresponding interest IDs to verify.
    • Returns: Status verification for each input, detailing validity and current audience size.

54. mcp_meta_ads_search_behaviors

    • Retrieves a directory of all available behavioral targeting classifications.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • limit: Maximum number of behaviors to catalogue (Default: 50).
    • Returns: A catalog of behavior options, detailing ID, name, audience bounds, hierarchy, and description.

55. mcp_meta_ads_search_demographics

    • Queries various categories within the demographic targeting schema.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • demographic_class: The subset to query ('demographics', 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os').
    • limit: Maximum records to return per class (Default: 50).
    • Returns: Structured data for the requested demographic type, including ID, name, audience estimates, and path information.

56. mcp_meta_ads_search_geo_locations

    • Performs a geographical search for targeting definitions.
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • query: Location keyword (e.g., "Texas", "London").
    • location_types: Filter by entity type (e.g., ['country', 'city', 'zip']).
    • limit: Maximum number of geographic results (Default: 25).
    • Returns: Location records containing unique keys, names, types, and hierarchical context.

57. mcp_meta_ads_search (Enhanced)

    • A generalized data-surface retrieval function spanning accounts, campaigns, advertisements, and associated Pages.
    • Auto-detection activates Page searching if query terms include "page" or "pages".
    • Inputs:
    • access_token (Optional): Token for Meta API access.
    • query: The generalized search string (e.g., "Stalled ad sets", "Brand X page").
    • Returns: A list of matching object identifiers formatted for seamless LLM consumption.

Licensing Framework

This Meta Ads Conduit is governed by the Business Source License 1.1, which grants the following freedoms:

• ✅ Usage Rights: Permitted for both personal use and commercial business operations.
• ✅ Adaptability: Full liberty to modify and tailor the source code.
• ✅ Distribution: Right to share the software with others.
• ✅ Full Open Source Transition: Automatically converts to Apache 2.0 licensing on January 1, 2029.

The sole prohibition is offering this system as a directly competing, hosted Software-as-a-Service solution. Inquiries regarding specific commercial licensing arrangements should be directed to the maintainers.

Data Privacy and Security Protocols

Meta Ads MCP adheres to rigorous security standards concerning credential management and automated authorization handling.

• Remote Conduit Mode: All sensitive authentication exchanges are managed within secure cloud infrastructure—no local storage of API tokens is necessary.
• Local Deployment Mode: Credentials are encrypted and stored securely on the local workstation. Consult the Local Installation Guide for exact storage specifications.

Connectivity Verification Procedures

To confirm the successful integration with your MCP client:

1. Confirm Account Linkage: Command your LLM to execute mcp_meta_ads_get_ad_accounts.
2. Inspect Entity Details: Follow up with mcp_meta_ads_get_account_info, substituting the appropriate account ID.
3. Inventory Check: Attempt to list top-level structures using mcp_meta_ads_get_campaigns.

For specific diagnostics related to local deployments, consult Local Installation Guide.

Issue Resolution Guide

💡 Expedient Solution: Bypass Local Configuration!

The simplest method to circumvent setup hurdles is to 🎯 utilize our Remote Conduit Service instead. This removes the need for software downloads, local configuration files, and immediately connects your ad entities for AI-driven analysis.

Local Deployment Difficulties

For comprehensive diagnostic procedures, debugging steps, and resolutions for local installation errors, refer to Local Installation Guide, which covers:

• Troubleshooting authorization failures.
• Solutions for installation dependency conflicts.
• Guidance on interpreting API response errors.
• Instructions for generating diagnostic logs.
• Techniques for performance tuning.

WIKIPEDIA: Business management tools encompass all systematic frameworks, computational applications, regulatory controls, analytical methodologies, and operational procedures employed by organizations to successfully navigate evolving market dynamics, maintain competitive parity, and systematically elevate corporate performance efficiency.

== General System Overview == These managerial instruments can be categorized based on the organizational function they serve. Examples include mechanisms for strategic foresight, workflow oversight, record keeping, human resource coordination, critical judgment, performance monitoring, and so forth. A functional taxonomy typically addresses these universal management domains:

Tools dedicated to data ingestion and input integrity across all departments. Software engineered for the governance and continuous refinement of operational workflows. Systems facilitating the aggregation of disparate data streams for informed decision-making. Modern management software has undergone radical transformation over the last decade, driven by accelerating technological advancement, making the selection of optimal business tools for any given enterprise context challenging. This complexity arises from the persistent imperative to reduce operational expenditure while simultaneously maximizing revenue streams, the demand for deep comprehension of consumer requirements, and the necessity of delivering requisite products in the precise format demanded by the market. Within this dynamic environment, executives must adopt a strategic posture toward selecting business management technology, rather than uncritically adopting the newest releases. Managers often integrate tools without adequate contextual tailoring, leading to operational instability. Consequently, business management systems must be chosen judiciously and subsequently customized to align precisely with the organization's unique operational needs, reversing the typical dependency.

== Prevalent Methodologies == In a 2013 assessment conducted by Bain & Company, an overview of global business tool adoption revealed patterns reflecting regional market needs and economic climates. The leading ten methods identified were:

Strategic planning frameworks Customer relationship management suites Employee satisfaction surveying tools Competitive benchmarking analysis Balanced scorecard implementation Core competency identification Outsourcing strategy definition Organizational change management programs Supply chain optimization modeling Mission and vision statement articulation Market segmentation analysis Total Quality Management (TQM) principles

== Corporate Software Ecosystems == Computer programs or collections of programs utilized by enterprise personnel to execute diverse business functions are termed business software (or enterprise applications). These applications are vital for augmenting productivity, quantitatively measuring output, and executing various corporate mandates with high fidelity. This evolution commenced with Management Information Systems (MIS), progressing through Enterprise Resource Planning (ERP) implementations. Subsequently, Customer Relationship Management (CRM) capabilities were integrated, culminating in the current paradigm of cloud-native business process management platforms. While a measurable correlation exists between Information Technology investment and organizational results, value maximization hinges on two critical factors: the proficiency of the deployment process and the rigorous suitability assessment and subsequent customization of the chosen technological apparatus.

== Tools for Small and Medium Enterprises (SMEs) == Solutions tailored for SMEs are crucial as they furnish mechanisms to efficiently conserve financial