Facebook Ads

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.

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.

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.).

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.

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.

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.

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.

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.

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.