Facebook Ads Agent#

Create, manage, and optimize Facebook/Meta Ads campaigns with full control over campaigns, ad sets, targeting, and creatives. Powered by AdAgent.

Security & Data Handling#

• MCP link is a credential: Your MCP Server URL ( https://adagent.10xboost.org/api/mcp/fb-ads/{user_id}/mcp) contains your user ID for credential lookup. Treat it like a password — do not share it publicly.
• Token scope: The service uses your Facebook OAuth token to access your ad accounts. It can create/modify campaigns, ad sets, and ads, manage budgets, and read performance data.
• Token storage: Your Facebook tokens are encrypted with Fernet (AES-128-CBC + HMAC) and stored in MongoDB. They are never exposed in API responses.
• Token expiry: Facebook long-lived tokens expire after ~60 days. Use refresh_token to extend when needed.
• Multi-tenant isolation: Each request is scoped to your user credentials via ASGI middleware. You can only access your own ad accounts.
• No local credentials: No local API keys, environment variables, or secrets are needed. All auth is embedded in the MCP link.
• Third-party service: This skill relies on AdAgent, an AI-powered ad management platform.

Prerequisites#

1. Sign up at adagent.10xboost.org with Google
2. Connect Facebook Ads — authorize AdAgent to access your Facebook Ad accounts
3. Get your MCP link: Copy your Facebook Ads MCP Server URL from the dashboard
4. Add to Claude: Paste the MCP link as a Connector — no install, no API key needed

Available Tools (22 tools)#

Account & Token#

ToolDescriptionlist_ad_accountsList all accessible ad accountsget_account_infoGet account details (currency, timezone, status)check_token_statusCheck token validity and expiryrefresh_tokenExchange short-lived token for long-lived token (60 days)

Campaign Management#

ToolDescriptionlist_campaignsList campaigns (filter by status)get_campaignGet campaign detailscreate_campaignCreate campaign (PAUSED by default)enable_campaignActivate a campaignpause_campaignPause a campaign

Ad Set Management#

ToolDescriptionlist_ad_setsList ad sets (filter by campaign/status)get_ad_setGet ad set details with full targetingcreate_ad_setCreate ad set with audience targetingenable_ad_setActivate an ad setpause_ad_setPause an ad set

Ad Management#

ToolDescriptionlist_adsList ads (filter by ad set/status)create_adCreate ad (upload image + creative + ad)enable_adActivate an adpause_adPause an ad

Performance & Insights#

ToolDescriptionget_account_insightsAccount-level performance dataget_campaign_insightsCampaign daily performanceget_ad_set_insightsAd set performance

Targeting Research#

ToolDescriptionsearch_interestsSearch interest targeting (e.g. "baseball", "cooking")search_locationsSearch geographic targeting (country, city, zip)search_targeting_categoriesBrowse targeting categories (interests, behaviors, demographics)

Compliance#

ToolDescriptionget_taiwan_regulation_statusCheck Taiwan ad regulation compliance

Workflow#

Creating a Full Ad (3-Layer Structure)#

Facebook Ads uses a 3-layer hierarchy: Campaign → Ad Set → Ad

Step 1: Create Campaign

text

create_campaign(
  name="Summer Sale 2026",
  objective="OUTCOME_TRAFFIC",
  daily_budget_usd=20.0
)

Objectives: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION

Budget rule: Set budget at Campaign OR Ad Set level, not both.

Step 2: Research Targeting

text

search_interests(query="AI")
search_locations(query="Taiwan", location_type="country")

Step 3: Create Ad Set (with targeting)

text

create_ad_set(
  name="AI Enthusiasts - TW",
  campaign_id="<campaign_id>",
  optimization_goal="LINK_CLICKS",
  billing_event="IMPRESSIONS",
  destination_type="WEBSITE",
  countries=["TW"],
  age_min=25,
  age_max=55,
  flexible_spec=[
    {"interests": [{"id": "6003087413192", "name": "AI"}]}
  ]
)

If Campaign has budget set, do NOT set daily_budget_usd on Ad Set.

Step 4: Create Ad

text

create_ad(
  name="Summer Sale Ad 1",
  ad_set_id="<ad_set_id>",
  image_url="https://example.com/ad-image.jpg",
  message="Summer Sale! 50% off all AI tools.",
  link="https://example.com/sale",
  call_to_action_type="SHOP_NOW"
)

CTA types: LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, BOOK_TRAVEL, CONTACT_US

Step 5: Enable (Campaign is PAUSED by default)

text

enable_campaign(campaign_id="<campaign_id>")
enable_ad_set(ad_set_id="<ad_set_id>")
enable_ad(ad_id="<ad_id>")

Checking Performance#

User RequestTool"How are my ads doing?"get_account_insights"Campaign X performance"get_campaign_insights"Ad set performance"get_ad_set_insights"List all campaigns"list_campaignstext

get_account_insights(
  start_date="2026-03-01",
  end_date="2026-03-30",
  time_increment="1"    // "1"=daily, "7"=weekly, "all_days"=summary
)

Present Results#

• Performance: Show metrics table (impressions, clicks, CTR, CPC, CPM, spend, reach, frequency)
• Campaign list: Show status, objective, budget, and delivery status
• Targeting: Show audience size estimates when researching interests

Targeting Tips#

• Use search_interests to find interest IDs before creating ad sets
• Use search_locations with location_type (country, city, zip, region) for geo-targeting
• flexible_spec items use OR within each element, AND between elements
• advantage_audience=1 enables Meta's Advantage+ automatic audience (recommended for beginners)

Error Handling#

ErrorSolutionToken expiredUse refresh_token or reconnect at adagent.10xboost.orgInvalid account IDRun list_ad_accounts to get valid IDsBudget conflictBudget must be at Campaign OR Ad Set level, not bothMissing Page IDSome objectives require page_id — get it from account infoTaiwan regulationRun get_taiwan_regulation_status to check complianceAd rejectedCheck Facebook ad policies — image text ratio, prohibited content

Documentation#

Product website: adagent.10xboost.org