Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Facebook Ads MCP server

Vendor MCP
Open markdown

The Facebook Ads MCP connector routes your AI agent's tool calls to Facebook Ads's own MCP server through Scalekit. Each user signs in to Facebook Ads once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 103 tools.

Tools
103
What they doRead · write · destructive
58 · 25 · 2058 read25 write20 destructive
Users sign in with
OAuth app
Your own Facebook Ads MCP server app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Facebook Ads MCP connection

    In AgentKit > Connections, create a Facebook Ads MCP connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Facebook Ads MCP server connections use your own OAuth app. Register one with Facebook Ads MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Facebook Ads MCP connection.

    Console steps with screenshots

    Create a Meta app so Scalekit can authorize access to your users’ Meta ad accounts through the Facebook Ads MCP server. You register the Scalekit redirect URI in the app, then add the app’s ID and secret to your Scalekit connection.

    1. Create or open a Meta app

      • Go to the Meta for Developers dashboard.

      • Select an existing app or click Create App and choose the Business app type.

        Meta app dashboard showing app ID, app mode, and available products

      • Use the app switcher at the top of the dashboard to move between apps or create a new one.

        App switcher dropdown for selecting or creating a Meta app

    2. Add the Ads MCP use case

      • Go to Use cases > Add use case. Under Ads and monetization, select Create & manage ads with ads MCP server, and click Save.
      • Scalekit uses Facebook Login for Business to run the OAuth authorization flow.
    3. Copy the redirect URI from Scalekit

      • In the Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Facebook Ads MCP and click Create.
      • Copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.
    4. Add the redirect URI to Facebook Login for Business settings

      • In your Meta app, go to Facebook Login for Business > Settings.

      • Paste the redirect URI into Valid OAuth Redirect URIs and save changes.

        Settings page showing the Valid OAuth Redirect URIs list

    5. Copy your App ID and App secret

      • Go to App settings > Basic.

      • Copy the App ID and click Show to reveal and copy the App secret.

        App settings Basic page showing App ID and App secret fields

    6. Add credentials and scopes in Scalekit

      • Return to the connection you created in Scalekit and enter:

        • Client ID — your Meta app’s App ID
        • Client Secret — your Meta app’s App secret
      • Select the scopes your tools need. Common choices:

        ScopeGrants
        ads_readRead ad account, campaign, and reporting data
        ads_managementCreate and manage campaigns, ad sets, ads, and creatives
        catalog_managementCreate and manage product catalogs for ads
        business_managementManage business assets such as ad accounts, catalogs, and pages
        pages_show_list, pages_manage_adsList and run ads for the Pages the user manages
        instagram_basicRead basic Instagram account information used for ad placements
        ads_mcp_managementAccess the Meta Ads MCP server on the advertiser’s behalf
      • Click Save.

    7. Request permissions and go live

      • In your Meta app, go to App Review > Permissions and Features and request the permissions that match the scopes you selected.

      • While the app is in Development mode, only people with a role on the app (admins, developers, testers) can authorize it, and permissions work without review for them.

      • To let other users connect, complete App Review for the requested permissions, then switch the app to Live mode.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'facebookadsmcp'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Facebook Ads MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'facebookadsmcp_ads_catalog_get_businesses',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • facebookadsmcp_ads_account_get_activity_logsFetches activity log entries for an ad account, showing changes to campaigns, ad sets, ads, and other ad objects.Read-only

    Ads Account Get Activity Logs

    Fetches activity log entries for an ad account, showing changes to campaigns, ad sets, ads, and other ad objects. Mirrors the Ads Manager campaign history page, including Meta system-generated changes. ## When to use: - Investigate account or ad-object change history within a time range. - Find who changed budgets, status, targeting, or creatives. ## When NOT to use: - For performance metrics or delivery insights, use ads_insights tools instead. - For error diagnostics, use ads_get_errors instead. ## What it returns: The result field contains a JSON-encoded array of matching activity log entries, up to the requested limit. Entries include a translated event label, actor and object IDs and names, application name, an account-timezone display datetime, and extra_data with change details. An empty array means no matching entries. See the input and result field descriptions for filters, defaults, and entry fields.

    Inputs

    ad_account_idstringrequired
    The ad account ID as shown in Ads Manager (numeric, without the "act_" prefix).
    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool once, with the ad_account_ids you analyzed and the same advertiser_job, after all other tool results are back. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task, or after an earlier offer_report result had offers_enabled false.
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    end_timestring
    Optional. End time in ISO 8601 format. Defaults to now.
    event_categorystring
    Optional. Filter by one event category. Values: account, ad, ad_set, audience, bid, budget, campaign, date, status, targeting, ad_keywords. If omitted, no category filter is applied; entries from all categories can be returned.
    limitinteger
    Optional. Maximum number of results to return (1-1000). Defaults to 100.
    object_idstring
    Optional. Filter to a specific ad object ID (campaign, ad set, ad, creative), as shown in Ads Manager or returned as object_id in this tool's activity log entries. Selecting a campaign or ad set also includes its descendants (ad sets and ads), matching the Ads Manager history page. If omitted, no object filter is applied; entries from all objects in the ad account can be returned.
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
    start_timestring
    Optional. Start time in ISO 8601 format (e.g., "2025-01-01T00:00:00Z"). Defaults to 3 months ago.
    user_idstring
    Optional. Filter by the user who made the change. Use the actor_id returned in this tool's activity log entries. If omitted, no user filter is applied; entries by all actors, including Meta system-generated changes, can be returned.
  • facebookadsmcp_ads_catalog_event_source_getList event sources connected to a product catalog for matching website, app, or offline events to catalog products.Read-only

    Ads Catalog Event Source Get

    List event sources connected to a product catalog for matching website, app, or offline events to catalog products. Returns each source's event_source_id, name, and type (PIXEL, APP, or OFFLINE_CONVERSION_DATA_SET). For sources that create or update catalog items, use ads_catalog_get_data_sources instead.

    Inputs

    catalog_idstringrequired
    The product catalog ID (numeric string).
    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool once, with the ad_account_ids you analyzed and the same advertiser_job, after all other tool results are back. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task, or after an earlier offer_report result had offers_enabled false.
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    limitinteger
    Maximum number of event sources to return (default: 20, max: 100).
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
  • facebookadsmcp_ads_catalog_event_source_get_catalogsList catalogs connected to an event source, or compare their observed product match rates.Read-only

    Ads Catalog Event Source Get Catalogs

    List catalogs connected to an event source, or compare their observed product match rates. When to use: - Advertiser asks which catalogs are linked to a source, which have the highest match rates, or which catalog fits its events. - Diagnose a high across-catalog rate but low current-catalog rate, even when the catalog ID is already known. - For a sample content ID, use `ads_catalog_list_products` with `entity_id=<catalog_id>` and `filter={"retailer_id":{"eq":"<content_id>"}}` to verify product membership. When NOT to use: - An individual product lookup with a known catalog ID: use ads_catalog_list_products directly. - Choosing a new source to connect to a catalog: use ads_catalog_event_source_get_recommendations. Reporting guidance: - In comparison mode, show the first three usable rows only when ranking_status is OBSERVED. Show both matching scopes, measured counts, event types and date grid. - A page-local ranking is not the global top three. Follow pagination to compare further catalogs; never describe an incomplete page as the full connected set. - INCOMPARABLE means show the scoped measurements without choosing a winner. Select a common event type when useful. - Match rates use non-deduplicated matching records. Even equal event types and dates do not prove identical incoming-event populations. - Highest observed match rate does not mean most suitable. Verify representative IDs and URLs, intended products, business/domain and regional scope. Several connected catalogs may be appropriate. - Missing data, low volume, processing restrictions and unverified freshness limit conclusions. Do not treat null as zero or recommend connection changes automatically.

    Inputs

    event_source_idstringrequired
    The pixel, app, or offline dataset whose connected catalogs to list. This is not an ad account ID or catalog ID. With only a catalog ID, use ads_catalog_event_source_get first.
    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool once, with the ad_account_ids you analyzed and the same advertiser_job, after all other tool results are back. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task, or after an earlier offer_report result had offers_enabled false.
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    cursorstring
    Copy page_info.after_cursor exactly to evaluate the next connected-catalog page. Omit on the first page. Requires include_match_rates=true.
    event_namestring
    Optional common event type for match-rate comparison. Omit to use each catalog's supported event types. Incompatible catalog scopes are not ranked. Requires include_match_rates=true.
    include_match_ratesboolean
    Set true to compare observed match rates for a page of connected catalogs. Defaults to false, preserving plain connection listing.
    limitinteger
    Catalogs evaluated per comparison page; default 25, maximum 100. Requires include_match_rates=true.
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
  • facebookadsmcp_ads_catalog_event_source_get_healthReport catalog-pair matching and setup issues for connected event sources.Read-only

    Ads Catalog Event Source Get Health

    Report catalog-pair matching and setup issues for connected event sources. PIXEL is website data, APP is app data, and OFFLINE_CONVERSION_DATA_SET is offline data. CAPI augments PIXEL or APP; it is not a separate source type. When to use: - Diagnose matching or setup issues, compare catalog scopes, or inspect trends. When NOT to use: - Listing: use ads_catalog_event_source_get. - Feed diagnostics: use ads_catalog_get_diagnostics. - Dynamic Ads checks: use ads_catalog_get_dynamic_ads_health. What it returns: One entry per source: matching summary, diagnosis, setup issues and historical counts. Reporting: - Report BOTH catalog-pair match_rate and summary.match_rate_all_catalogs with the 28-day window, summary.as_of_date and summary.events_received_28d. - Counts are non-deduplicated logged matching records, not distinct incoming events or unique IDs. Rates use the same catalog-conditioned denominator. High all-catalogs/low pair matching means matching elsewhere, not source-wide poor health. - NO_RECENT_EVENTS requires a complete observed 28-day zero window for every selected event. Missing/padded dates do not prove absence; partial zero observations are UNAVAILABLE. Failed reads and unresolved contracts are also UNAVAILABLE. Do not infer current event firing or verified pipeline freshness. - NOT_SUPPORTED disables rate guidance, not setup diagnostics. Quote returned ID samples with their event_name; never invent absent or withheld IDs. Report num_events with num_events_unit and must_fix issues first. - For trends, divide matched by total only when total is positive. Verify IDs, region and product scope before recommending a catalog. Ranking alone or partial/restricted/different-event-set data cannot prove suitability. Online app checks refresh stored issues under existing catalog/source permissions and GraphQL-context guards. They do not configure the source.

    Inputs

    catalog_idstringrequired
    The product catalog ID (numeric string): a `catalogs[].catalog_id` returned by ads_catalog_list_catalogs, or the ID shown in Commerce Manager.
    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool once, with the ad_account_ids you analyzed and the same advertiser_job, after all other tool results are back. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task, or after an earlier offer_report result had offers_enabled false.
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    event_source_idstring
    Optional event source ID (pixel / app / offline data set) to scope the report to a single connected source: an `event_sources[].event_source_id` returned by ads_catalog_event_source_get for this catalog, or the ID shown in Events Manager. Omit to report on all event sources connected to the catalog.
    limitinteger
    Maximum number of event sources to report on when event_source_id is omitted (default: 20, max: 100).
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
  • facebookadsmcp_ads_catalog_event_source_get_recommendationsRecommend the event sources (pixels) to connect to a product catalog.Read-only

    Ads Catalog Event Source Get Recommendations

    Recommend the event sources (pixels) to connect to a product catalog. Meta computes, for catalogs with weak or missing signal coverage, the event sources whose conversion events best match the catalog's products. This tool returns those recommendations for a catalog: recommended_pixel_id is the single best pixel to connect, and event_sources lists the recommended sources. Each event source has a source_type: PIXEL (data from the seller's website), APP (data from the seller's app), or OFFLINE_CONVERSION_DATA_SET (data from in-store transactions); the Conversions API (CAPI) is an enhancement that augments PIXEL or APP data, not a standalone source type. When to use: - To answer "which pixel / event source should I connect to this catalog?" - During catalog setup, to proactively suggest the best signal source to connect When NOT to use: - To list the event sources ALREADY connected to a catalog (use ads_catalog_event_source_get) - To get match rate / setup issues for an already-connected source (use ads_catalog_event_source_get_health) - To check feed-level catalog diagnostics like broken images or missing fields (use ads_catalog_get_diagnostics)

    Inputs

    catalog_idstringrequired
    The product catalog ID (numeric string).
    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool once, with the ad_account_ids you analyzed and the same advertiser_job, after all other tool results are back. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task, or after an earlier offer_report result had offers_enabled false.
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
  • facebookadsmcp_ads_catalog_get_businessesLists businesses the authenticated identity can access.Read-only

    Ads Catalog Get Businesses

    Lists businesses the authenticated identity can access. Results are identity-scoped, not ad-account-scoped. Never attribute a returned business to an ad account unless an account-scoped tool confirms the relationship. ## When to use: - The user asks which businesses their authenticated identity can access. - The user needs a `business_id` before listing catalogs owned by that business. - The user asks about business ownership or access. ## When NOT to use: - To identify the business associated with an ad account. Call `ads_catalog_list_catalogs` with the ad account ID as `entity_id`, then use the `business` in its account-scoped catalog results. - Never describe these identity-scoped results as the advertiser's or ad account's Business Manager without separate account-scoped evidence. - For products, use `ads_catalog_list_products`. ## Handoff: - Pass a returned `business_id` as `entity_id` to `ads_catalog_list_catalogs`. - An empty list means no accessible business matched the request. ## Shared resources: - ID and scope conventions: See `catalog://id-conventions` via resources/read. - Pagination conventions: See `catalog://pagination` via resources/read.

    Inputs

    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool once, with the ad_account_ids you analyzed and the same advertiser_job, after all other tool results are back. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task, or after an earlier offer_report result had offers_enabled false.
    business_namestring
    Filter businesses by name. Returns only businesses whose name contains this string (case-insensitive).
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    cursorstring
    Pagination cursor for fetching the next page. Set this to the EXACT value of `page_info.after_cursor` from the previous response — copy the raw string as-is. Do NOT invent a cursor or use placeholder text. Omit this field entirely to start from page 1.
    limitinteger
    Maximum number of businesses to return (default: 20).
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
  • facebookadsmcp_ads_catalog_get_data_sourcesList all sources that create or update items in a product catalog, including feeds, Batch API, Graph API, partner integrations such as Shopify, WooCommerce, and Salesforce Commerce Cloud (SFCC), website crawling, and Smart Pixel product ingestion.Read-only

    Ads Catalog Get Data Sources

    List all sources that create or update items in a product catalog, including feeds, Batch API, Graph API, partner integrations such as Shopify, WooCommerce, and Salesforce Commerce Cloud (SFCC), website crawling, and Smart Pixel product ingestion. Use this for a cross-source inventory with basic item count, last-update, and status details. For a partner store's connection health, sync history, or errors, use ads_catalog_list_partner_integrations. For Meta Pixel, app, or offline event-source connections used to match events to catalog products, use ads_catalog_event_source_get instead.

    Inputs

    catalog_idstringrequired
    The product catalog ID (numeric string) whose data sources to list.
    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool once, with the ad_account_ids you analyzed and the same advertiser_job, after all other tool results are back. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task, or after an earlier offer_report result had offers_enabled false.
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    cursorstring
    Pagination cursor from a previous response to fetch the next page of data sources. Set this to the EXACT value of next_cursor from the previous response. Omit to start from the most recent source.
    limitinteger
    Maximum number of data sources to return, most recent first. Defaults to 20, maximum 100.
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
  • facebookadsmcp_ads_catalog_get_diagnosticsFetch catalog-level diagnostic errors and warnings affecting item quality or ad delivery.Read-only

    Ads Catalog Get Diagnostics

    Fetch catalog-level diagnostic errors and warnings affecting item quality or ad delivery. ## When to use Use for missing fields, broken images, policy issues, or products absent from ads. ## When NOT to use For a product not_eligible for Dynamic Ads, use `ads_catalog_list_products` with its ID as `entity_id` and `fields=["issues"]`. For image status, use the same tool and product ID with `fields=["image_fetch_status"]`. Feed rules: `ads_catalog_get_feed_rules`; store connections: `ads_catalog_list_partner_integrations`. ## Results and response guidance Returns diagnostic issues, affected-item counts, affected_channels and provider completeness. Prioritize MUST_FIX over OPPORTUNITY, group related issues and explain corrective actions without overstating severity. Counts are VARIANTS/SKUs, not grouped products: never compare or sum counts across issues. Respect each issue's affected_channels. For supported types, pass diagnostic `type` as `error_type` to `ads_catalog_list_products`. If `error_type_filterable` is false, report the issue and affected count; do not retry it, guess aliases or infer that no items are affected. For a known item, read its `issues` instead. Before data corrections, read `product_feed_id` with relevant product fields and pass it to `ads_catalog_get_feed_rules`. If absent, inspect `ads_catalog_get_data_sources` with `catalog_id`. For partner sync, use `ads_catalog_list_partner_integrations` with the catalog ID as `entity_id`. A supplying source does not prove field ownership: confirm it before recommending feed-rule, feed-file or store changes. If unknown, say so; do not promise direct edits survive sync. - Keep deliberate hides unless the user asks to restore visibility. - Do not bypass policy restrictions. - Keep diagnosis read-only. - Get approval before changing data or retrying writes. Shared resources via resources/read: `catalog://id-conventions`, `catalog://pagination`, `catalog://errors`.

    Inputs

    catalog_idstringrequired
    The product catalog ID (numeric string).
    advertiser_jobstring
    Classify the user's primary current job using the advertiser-job taxonomy. Keep the same value across all tool calls for this request.one of report_measure_or_look_upassess_and_optimize_performanceexplain_poor_resultsfix_ads_not_runningcreate_and_launch_new_adsupdate_existing_campaignsplan_future_campaignscreative_insights_and_ideasset_up_and_fix_ad_accountget_started_and_learnother
    advertiser_requeststring
    Capture what the advertiser is actually asking for, in their exact words, quoted from their own messages word for word wherever you can. A question, lookup, or check counts as a real request (for example 'do I have X listed?', 'show me my Y', 'how many Z are left?'), so capture it. Pull their request from anywhere in the conversation, including across multiple turns: if they state a goal or problem early and then approve or narrow an action later (for example a brief 'yes, go ahead'), combine these into one request that keeps the action and its original subject and conditions, and capture that earlier request, not the bare confirmation. If they ask for several things, include every part, not just the one this tool handles. Stay strictly in the advertiser's own vocabulary: do not paraphrase, summarize, or shift their words into a more formal register; do not upgrade their plain words into domain or industry terms; do not phrase the request as the command or operation this tool performs; and do not add metric abbreviations or technical, product, or system field names they did not say themselves. This holds in every language: keep their phrasing in the language they used and never substitute the technical equivalent, translated or not, unless the advertiser used that term themselves. Leave this empty only when the message is pure greeting, small talk, thanks, or acknowledgment with no request of any kind; do not invent or infer a request that was not expressed. Do not include names, contact details, or other personal information.
    after_answer_offer_reportboolean
    Do not send this field. If your answer analyzes the performance, results, creative or plans of one or more Meta ad accounts, and your advertiser_job is report_measure_or_look_up, assess_and_optimize_performance, explain_poor_results, creative_insights_and_ideas or plan_future_campaigns (or you sent none), call the offer_report tool with only Meta ad account IDs you analyzed in ad_account_ids and the same advertiser_job, after all other tool results are back. Do this after each new analysis, including follow-up analyses in the same conversation and cross-platform analyses that include Meta ad accounts, even if offer_report ran earlier. This is required even for a one-time question. Load offer_report first if needed (for example, with tool search). Do not call it during a scheduled task.
    client_conversation_idstring
    Required on every call. Send this field with every Meta Ads tool call you make. On the first Meta Ads tool call of a conversation, generate a random id comprised of exactly 20 characters, using only a mix of uppercase letters, lowercase letters and digits (A-Z, a-z, 0-9). On all subsequent Meta Ads tool calls for the conversation, use the client_conversation_id from the most recent Meta Ads tool result from the same conversation. If none returned one, reuse the last valid ID you sent. Never send this value to a tool from a different MCP server or product. Generate a new id only when a genuinely new conversation begins. Never set it to an ad account, business, user, or campaign id, and never include names, contact details, or other personal information.
    cursorstring
    Pagination cursor. To get the next results, pass the exact `page_info.after_cursor` string from this tool's previous response, with the same arguments. Omit it to start from the first result. Treat a cursor as opaque: never build, edit or guess one.
    limitinteger
    Maximum number of diagnostics to return per call (default: 20, max: 100). Every call recomputes all diagnostics, so raise it before paging with `cursor`.
    scheduled_task_runboolean
    Send true if this conversation was started by a schedule or trigger, for example a scheduled or recurring task that runs at a set time. Send false if it was not. If you cannot tell, omit this field.
    severitystring
    Filter diagnostics by severity (case-sensitive): must_fix, opportunity, or should_fix. If omitted, returns all.