{"passport":{"unfragile":{"@version":"1.0","version":"2026-05","artifact":{"id":"awesome-facebook-ads","slug":"facebook-ads","name":"Facebook Ads","type":"mcp","url":"https://github.com/gomarble-ai/facebook-ads-mcp-server","page_url":"https://unfragile.ai/facebook-ads","categories":["mcp-servers"],"tags":[],"pricing":{"model":"open_source","free":true,"starting_price":null},"status":"active","verified":false},"capabilities":[{"id":"awesome-facebook-ads__cap_0","uri":"capability://tool.use.integration.mcp.native.facebook.ads.api.bridging.with.fastmcp.framework","name":"mcp-native facebook ads api bridging with fastmcp framework","description":"Implements a FastMCP-based middleware layer that translates MCP tool requests into authenticated Facebook Graph API calls using the requests HTTP client. The server.py entry point handles JSON-RPC protocol communication over stdin/stdout, avoiding network port dependencies and enabling direct integration with MCP clients like Claude Desktop and Cursor IDE. Each of the 21 MCP tools maps to specific Graph API endpoints with automatic request/response serialization.","intents":["I want to connect my Claude Desktop or Cursor IDE to Facebook Ads without building custom API wrappers","I need to expose Facebook Ads functionality through the MCP protocol for AI agent integration","I want to avoid managing HTTP ports and network configuration for local AI tool integration"],"best_for":["AI agent builders integrating Facebook Ads into Claude Desktop workflows","Teams building MCP-compatible advertising automation tools","Developers wanting standardized protocol access to Meta's advertising platform"],"limitations":["Requires valid Meta access token with appropriate Facebook Ads permissions scopes","Communication limited to stdin/stdout — no concurrent request handling across multiple clients","FastMCP framework version ≥1.6.0 required; older versions lack necessary MCP spec compliance"],"requires":["Python 3.10+","FastMCP ≥1.6.0","requests library ≥2.32.3","Valid Meta access token with ads_management scope","MCP-compatible client (Claude Desktop, Cursor IDE, or custom MCP client)"],"input_types":["JSON-RPC tool requests with structured parameters","Meta access token (environment variable or configuration)"],"output_types":["JSON-RPC responses with Graph API data","Structured campaign/ad/insight objects from Facebook Ads API"],"categories":["tool-use-integration","api-bridging"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_1","uri":"capability://data.processing.analysis.account.level.facebook.ads.data.aggregation.and.hierarchy.traversal","name":"account-level facebook ads data aggregation and hierarchy traversal","description":"Provides 7 account-level MCP tools that aggregate data across the full Facebook Ads entity hierarchy (accounts → campaigns → ad sets → ads → insights). Tools query the Graph API with account ID as the root parameter and traverse child entities, returning paginated results with filtering and field selection. Implements the Facebook Ads object model where accounts contain campaigns, campaigns contain ad sets, and ad sets contain individual ads with associated creative and performance data.","intents":["I need to list all campaigns under a Facebook Ads account and their current status","I want to retrieve account-level insights (spend, impressions, conversions) aggregated across all campaigns","I need to enumerate all ad sets and ads within an account to audit structure and targeting"],"best_for":["Advertising managers auditing account structure and campaign organization","AI agents performing account-wide performance analysis and reporting","Automation tools that need to discover and iterate over all ads in an account"],"limitations":["Pagination required for accounts with >100 campaigns or ad sets; default limit is 25 results per request","Account ID must be known in advance; no account discovery tool for users with multiple ad accounts","Insights data has 1-day latency from Facebook; real-time performance data unavailable"],"requires":["Valid Meta access token with ads_management scope","Facebook Ads account ID (ad_account_XXXXXXXXX format)","Appropriate account permissions (Admin or Analyst role minimum)"],"input_types":["Account ID (string, format: ad_account_XXXXXXXXX)","Optional filters (campaign status, date range for insights)","Optional field selectors (which metrics to return)"],"output_types":["Structured JSON arrays of campaign objects with name, status, budget, schedule","Aggregated insight metrics (spend, impressions, clicks, conversions, ROAS)","Nested hierarchy data showing campaigns → ad sets → ads relationships"],"categories":["data-processing-analysis","search-retrieval"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_2","uri":"capability://automation.workflow.campaign.and.ad.set.creation.with.budget.and.targeting.configuration","name":"campaign and ad set creation with budget and targeting configuration","description":"Exposes MCP tools for creating and updating Facebook Ads campaigns and ad sets with full parameter control over budget allocation, scheduling, targeting criteria, and optimization objectives. Tools construct Graph API POST requests with campaign/ad set objects, validating required fields (name, objective, budget_type) and optional targeting parameters (age, location, interests, custom audiences). Supports both daily and lifetime budgets, campaign scheduling with start/end dates, and objective selection (REACH, TRAFFIC, CONVERSIONS, etc.).","intents":["I want to programmatically create a new campaign with specific budget and scheduling parameters","I need to create ad sets within a campaign with custom audience targeting and daily budget limits","I want to update campaign objectives and budgets without manual Facebook Ads Manager access"],"best_for":["Advertising automation platforms building campaign creation workflows","AI agents that need to launch campaigns based on business rules or performance triggers","Teams managing multiple ad accounts and needing programmatic campaign setup"],"limitations":["Campaign creation requires pre-existing billing account with payment method on file","Targeting parameters (interests, custom audiences) must reference existing Facebook audience IDs; no audience creation tool provided","Budget changes on active campaigns may have restrictions; Facebook enforces minimum spend thresholds for certain objectives","Campaign objective cannot be changed after creation; requires campaign deletion and recreation"],"requires":["Valid Meta access token with ads_management scope","Facebook Ads account ID with active billing setup","Campaign name, objective type, and budget amount as minimum parameters","For targeting: existing audience IDs, location codes, or interest category IDs from Facebook's taxonomy"],"input_types":["Campaign object: {name, objective, budget_type, daily_budget or lifetime_budget, start_time, end_time}","Ad set object: {name, campaign_id, daily_budget, targeting (age, location, interests, custom_audiences), optimization_goal}","Targeting parameters: audience IDs, location codes, interest IDs, demographic filters"],"output_types":["Created campaign object with campaign_id, status, created_time","Created ad set object with ad_set_id, status, budget configuration","Error responses with validation details if required fields missing or invalid"],"categories":["automation-workflow","tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_3","uri":"capability://automation.workflow.ad.creative.management.with.asset.upload.and.variant.creation","name":"ad creative management with asset upload and variant creation","description":"Exposes MCP tools for creating and managing ad creatives (images, videos, carousels) and ad variants within ad sets. Tools handle creative asset specification (image URLs, video URLs, or carousel card definitions), copy text, headlines, and call-to-action buttons. Supports creating multiple ad variants from a single ad set to enable A/B testing. Implements the Facebook Ads creative object model where creatives are associated with ads, and ads are associated with ad sets, enabling multi-variant campaign testing.","intents":["I want to create multiple ad variants with different copy and images to test performance","I need to add video or carousel creatives to an existing ad set programmatically","I want to manage ad copy, headlines, and CTAs without using the Facebook Ads Manager UI"],"best_for":["Performance marketing teams running A/B tests across creative variants","AI agents generating and testing multiple ad variations based on audience segments","Automation platforms that need to create ads at scale with dynamic copy and imagery"],"limitations":["Image assets must be pre-uploaded to Facebook or provided as external URLs; no direct file upload from local filesystem","Video creatives require videos already uploaded to Facebook; no video transcoding or format conversion","Carousel ads limited to 10 cards maximum per Facebook's constraints","Creative approval process is asynchronous; newly created ads may be in 'PENDING_REVIEW' status for 24+ hours"],"requires":["Valid Meta access token with ads_management scope","Ad set ID to associate creatives with","For image ads: image URL or Facebook image asset ID","For video ads: Facebook video asset ID (pre-uploaded)","Ad copy text, headline, and call-to-action button text"],"input_types":["Creative object: {image_url or video_id, ad_name, adset_id, creative_data (body, headline, call_to_action_type)}","Carousel creative: array of {image_url, headline, description, link_url} objects (max 10 cards)","A/B test parameters: variant labels, creative variations to test"],"output_types":["Created ad object with ad_id, status (PENDING_REVIEW or ACTIVE), created_time","Creative object with creative_id and asset references","Validation errors if creative assets invalid or missing required fields"],"categories":["automation-workflow","image-visual"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_4","uri":"capability://data.processing.analysis.performance.insights.and.analytics.retrieval.with.metric.aggregation","name":"performance insights and analytics retrieval with metric aggregation","description":"Provides MCP tools for querying Facebook Ads performance metrics (spend, impressions, clicks, conversions, ROAS, CPC, CTR) at account, campaign, ad set, and ad levels. Tools construct Graph API requests with date range parameters and metric field selectors, returning time-series or aggregated data. Implements Facebook's insights API with automatic metric calculation (e.g., CTR = clicks / impressions) and supports breakdowns by device, platform, and demographic. Data has 1-day latency from Facebook's reporting pipeline.","intents":["I want to retrieve campaign performance metrics (spend, conversions, ROAS) for a specific date range","I need to compare performance across multiple ad sets to identify top performers","I want to pull insights data for reporting and dashboard integration without manual Facebook Ads Manager exports"],"best_for":["Analytics platforms and dashboards aggregating Facebook Ads performance data","AI agents analyzing campaign performance to recommend optimizations","Reporting tools that need automated daily/weekly performance summaries"],"limitations":["Insights data has 1-day latency; real-time performance metrics unavailable","Date range limited to 90 days of historical data for most metrics; longer periods require multiple API calls","Certain metrics (e.g., conversion value) only available if conversion tracking properly configured on account","Breakdowns by demographic or device add latency and may return sparse data for small audiences"],"requires":["Valid Meta access token with ads_management scope","Entity ID (account, campaign, ad set, or ad ID) to query","Date range (start_date, end_date in YYYY-MM-DD format)","Metric field names (spend, impressions, clicks, conversions, etc.)"],"input_types":["Entity ID (account_id, campaign_id, adset_id, or ad_id)","Date range: {start_date, end_date} in YYYY-MM-DD format","Metric selectors: array of metric names (spend, impressions, clicks, conversions, cpc, ctr, roas)","Optional breakdowns: device_type, platform, demographic"],"output_types":["Time-series insight data: array of {date, spend, impressions, clicks, conversions, calculated_metrics}","Aggregated metrics: {total_spend, total_impressions, total_conversions, avg_cpc, avg_ctr, roas}","Breakdown data: metrics segmented by device, platform, or demographic"],"categories":["data-processing-analysis","search-retrieval"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_5","uri":"capability://automation.workflow.campaign.status.and.budget.management.with.real.time.updates","name":"campaign status and budget management with real-time updates","description":"Exposes MCP tools for updating campaign and ad set status (ACTIVE, PAUSED, DELETED) and budget parameters (daily_budget, lifetime_budget, budget_remaining) in real-time. Tools construct Graph API PATCH requests with status and budget fields, enabling immediate campaign pause/resume and budget adjustment without Facebook Ads Manager UI. Changes propagate to Facebook's system within seconds, affecting ad delivery immediately.","intents":["I want to pause a campaign immediately if performance drops below a threshold","I need to increase daily budget for a high-performing ad set programmatically","I want to stop spending on underperforming campaigns without manual intervention"],"best_for":["Performance marketing automation that reacts to real-time metrics","AI agents implementing budget optimization rules based on ROAS or CPA targets","Teams managing campaigns across multiple accounts with centralized control"],"limitations":["Budget changes on active campaigns may have minimum spend thresholds; Facebook may reject very low budgets","Status changes (ACTIVE → PAUSED) take effect within seconds but may not be immediately reflected in insights data","Cannot delete campaigns with active ads; must pause or delete ads first","Budget increases may require account credit availability; insufficient funds will cause API error"],"requires":["Valid Meta access token with ads_management scope","Campaign or ad set ID to update","New status value (ACTIVE, PAUSED, DELETED) or new budget amount","Account must have sufficient billing credits for budget increases"],"input_types":["Campaign/ad set ID (string)","Status update: {status: 'ACTIVE' | 'PAUSED' | 'DELETED'}","Budget update: {daily_budget or lifetime_budget: integer (in account currency cents)}"],"output_types":["Updated campaign/ad set object with new status and budget values","Confirmation of status change with effective timestamp","Error response if budget insufficient or status change invalid"],"categories":["automation-workflow","tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_6","uri":"capability://automation.workflow.multi.deployment.configuration.with.environment.based.authentication","name":"multi-deployment configuration with environment-based authentication","description":"Supports three distinct deployment paths (automated GoMarble setup, manual development configuration, Claude Desktop CLI installation) that converge to the same operational state with 21 MCP tools available. Authentication uses Meta access tokens passed via environment variables (FACEBOOK_ACCESS_TOKEN) or configuration files, with optional integration to GoMarble's token service for automated token refresh. The server.py entry point accepts command-line arguments for token and account ID, enabling flexible deployment across local development, Docker containers, and cloud environments.","intents":["I want to deploy the Facebook Ads MCP server locally for development without complex setup","I need to run the server in Docker with environment variable-based authentication","I want to integrate the server with Claude Desktop using the CLI installer"],"best_for":["Developers setting up local MCP development environments","DevOps teams deploying MCP servers in containerized infrastructure","Non-technical users installing MCP tools via Claude Desktop CLI"],"limitations":["Manual configuration requires understanding of environment variables and file paths","Docker deployment requires Docker installation and basic container knowledge","Token refresh via GoMarble service requires internet connectivity and service availability","CLI installer only works with Claude Desktop; other MCP clients require manual configuration"],"requires":["Python 3.10+ for local/manual deployment","Docker for containerized deployment","Valid Meta access token (obtainable from Facebook Developers console)","For Claude Desktop: Claude Desktop application installed"],"input_types":["Environment variable: FACEBOOK_ACCESS_TOKEN","Optional: Facebook Ads account ID","Optional: GoMarble token service credentials"],"output_types":["Running MCP server process listening on stdin/stdout","21 MCP tools registered and available to MCP clients","Deployment confirmation with tool availability status"],"categories":["automation-workflow","tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_7","uri":"capability://data.processing.analysis.audience.targeting.and.custom.audience.integration","name":"audience targeting and custom audience integration","description":"Provides MCP tools for specifying and applying audience targeting parameters (age ranges, locations, interests, custom audiences, lookalike audiences) when creating ad sets. Tools accept targeting objects with demographic filters, geographic location codes, Facebook interest category IDs, and references to pre-existing custom audiences. Implements Facebook's targeting taxonomy with validation of location codes (country, region, city) and interest category IDs. Does not create audiences; only applies existing audience definitions to ad sets.","intents":["I want to create an ad set targeting women aged 25-34 in specific US cities interested in fitness","I need to apply a custom audience (email list or website visitor pixel) to an ad set","I want to create lookalike audiences based on existing customer lists and apply them to campaigns"],"best_for":["Performance marketers building targeted campaigns with demographic and interest filters","E-commerce platforms applying customer list targeting to retargeting campaigns","AI agents generating audience-specific ad sets based on business rules"],"limitations":["Custom audiences must be pre-created in Facebook Ads Manager; no audience creation tool provided","Interest category IDs must reference Facebook's interest taxonomy; invalid IDs cause ad set creation failure","Location codes must use Facebook's location ID format; country/region/city codes not interchangeable","Lookalike audiences require source audience with minimum 100 matching users; smaller audiences cannot generate lookalikes"],"requires":["Valid Meta access token with ads_management scope","For demographic targeting: age range (min_age, max_age), gender (if applicable)","For location targeting: Facebook location IDs (country, region, city codes)","For interest targeting: Facebook interest category IDs from the interest taxonomy","For custom audiences: pre-existing custom audience IDs from Facebook Ads account"],"input_types":["Targeting object: {age_min, age_max, genders, locations, interests, custom_audiences, lookalike_audiences}","Location codes: Facebook location ID format (e.g., 6003 for United States)","Interest IDs: Facebook interest category IDs (e.g., 6003139 for 'Fitness enthusiasts')","Custom audience IDs: pre-created audience IDs from account"],"output_types":["Validated targeting object applied to ad set","Ad set created with targeting parameters","Error response if location codes, interest IDs, or audience IDs invalid"],"categories":["data-processing-analysis","tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"awesome-facebook-ads__cap_8","uri":"capability://safety.moderation.error.handling.and.validation.with.graph.api.error.translation","name":"error handling and validation with graph api error translation","description":"Implements error handling that translates Facebook Graph API error responses into human-readable MCP error messages with actionable guidance. Validates required parameters before API calls (campaign name, budget amount, targeting parameters) and returns structured error objects with error codes, descriptions, and suggested remediation steps. Handles common failures: invalid account IDs, insufficient billing credits, invalid audience/interest IDs, permission scopes missing, and rate limiting.","intents":["I want clear error messages when campaign creation fails due to invalid parameters","I need to understand why an ad set targeting configuration was rejected","I want to know if my access token lacks required permissions before attempting operations"],"best_for":["Developers debugging MCP tool integration issues","AI agents that need to interpret errors and retry with corrected parameters","Automation systems that need to log and alert on API failures"],"limitations":["Error messages depend on Facebook Graph API error response quality; some errors lack detailed context","Rate limiting errors may not indicate exact retry-after time; exponential backoff required","Permission scope errors only detected at API call time; no pre-flight permission check available","Validation only covers required fields; optional parameter validation deferred to Graph API"],"requires":["Valid Meta access token (errors will indicate if token invalid or expired)","Proper parameter formatting (campaign names, budget amounts, date formats)"],"input_types":["Any MCP tool request with potentially invalid parameters"],"output_types":["Structured error object: {error_code, error_message, suggested_action}","Validation error: {field, reason, expected_format}","Rate limit error: {error_code: 'RATE_LIMIT', retry_after_seconds}"],"categories":["safety-moderation","tool-use-integration"],"confidence":0.5,"matches":0,"success_rate":0}],"trust":{"score":30,"verified":false,"data_access_risk":"high","permissions":["Python 3.10+","FastMCP ≥1.6.0","requests library ≥2.32.3","Valid Meta access token with ads_management scope","MCP-compatible client (Claude Desktop, Cursor IDE, or custom MCP client)","Facebook Ads account ID (ad_account_XXXXXXXXX format)","Appropriate account permissions (Admin or Analyst role minimum)","Facebook Ads account ID with active billing setup","Campaign name, objective type, and budget amount as minimum parameters","For targeting: existing audience IDs, location codes, or interest category IDs from Facebook's taxonomy"],"failure_modes":["Requires valid Meta access token with appropriate Facebook Ads permissions scopes","Communication limited to stdin/stdout — no concurrent request handling across multiple clients","FastMCP framework version ≥1.6.0 required; older versions lack necessary MCP spec compliance","Pagination required for accounts with >100 campaigns or ad sets; default limit is 25 results per request","Account ID must be known in advance; no account discovery tool for users with multiple ad accounts","Insights data has 1-day latency from Facebook; real-time performance data unavailable","Campaign creation requires pre-existing billing account with payment method on file","Targeting parameters (interests, custom audiences) must reference existing Facebook audience IDs; no audience creation tool provided","Budget changes on active campaigns may have restrictions; Facebook enforces minimum spend thresholds for certain objectives","Campaign objective cannot be changed after creation; requires campaign deletion and recreation","builder identity is not verified yet","no observed match outcomes yet"],"rank_breakdown":{"adoption":0.05,"quality":0.43,"ecosystem":0.39999999999999997,"match_graph":0.25,"freshness":0.52,"weights":{"adoption":0.25,"quality":0.25,"ecosystem":0.15,"match_graph":0.23,"freshness":0.12}},"observed_outcomes":{"matches":0,"success_rate":0,"avg_confidence":0,"top_intents":[],"last_matched_at":null},"maintenance":{"status":"active","updated_at":"2026-06-17T09:51:03.039Z","last_scraped_at":"2026-05-03T14:00:15.503Z","last_commit":null},"community":{"stars":null,"forks":null,"weekly_downloads":null,"model_downloads":null,"model_likes":null}},"distribution":{"claim_url":"https://unfragile.ai/submit?claim=facebook-ads","compare_url":"https://unfragile.ai/compare?artifact=facebook-ads"}},"signature":"597qy2z3BHyncjVGtwQ2ifvnwEdm2F43PWOSx+QLtF3TwI74QDDTUYu+PpDxLErKY4eAwbz0n3EMszja2qusBw==","signedAt":"2026-06-22T02:40:37.251Z","signedBy":"unfragile.ai","version":1},"_links":{"self":"https://unfragile.ai/api/v1/passport/facebook-ads","artifact":"https://unfragile.ai/facebook-ads","verify":"https://unfragile.ai/api/v1/verify?slug=facebook-ads","publicKey":"https://unfragile.ai/api/v1/trust-passport-public-key","spec":"https://unfragile.ai/trust","schema":"https://unfragile.ai/schema.json","docs":"https://unfragile.ai/docs"}}