Meta Ads Remote MCP

Instantiates a FastMCP server that routes all entry points (CLI, Python module, library import, remote HTTP) through a unified server.py core, configuring transport mechanisms (stdio for local clients, streamable-http for remote cloud deployment) based on deployment context. Uses FastMCP's decorator-based tool registration pattern to expose 29+ specialized tools as MCP resources without manual protocol serialization.

Implements MetaAuthManager class that handles OAuth 2.0 token exchange with Meta's Graph API, caching tokens in platform-specific storage (filesystem for local deployment, environment variables for remote). Supports token refresh logic with expiration tracking, enabling seamless re-authentication without user intervention. Integrates with Meta's OAuth endpoints to exchange authorization codes for long-lived access tokens scoped to advertising permissions.

Exposes tools for retrieving ad account information, listing accessible ad accounts, and managing account-level settings. Implements account discovery through Meta's Account API, returning account IDs, names, currencies, timezones, and account status. Supports multi-account workflows where single MCP client can operate across multiple ad accounts by specifying account ID in tool parameters. Enables account switching and account-level configuration management.

Implements centralized API class (meta_ads_mcp/core/api.py) that handles all HTTP communication with Meta Graph API, providing automatic error translation, retry logic with exponential backoff, request logging, and response parsing. Abstracts HTTP complexity from tool implementations, enabling tool functions to focus on business logic rather than HTTP handling. Supports rate limit handling with automatic backoff when approaching API quotas.

Implements PipeboardAuthManager class that validates incoming requests against Pipeboard-issued tokens, enabling secure remote access to the MCP server without exposing Meta credentials. Tokens can be provided via environment variables or URL query parameters, with validation occurring at request entry point before tool execution. Enables multi-tenant access control where different users/teams receive different tokens with isolated access.

Exposes tools for creating, reading, updating, and deleting Meta advertising campaigns through decorated Python functions that map to Meta Graph API endpoints. Supports campaign lifecycle management including budget allocation, daily/lifetime spend limits, campaign status transitions (ACTIVE/PAUSED/ARCHIVED), and campaign objective selection (REACH, CONVERSIONS, TRAFFIC, etc.). Uses centralized API layer for HTTP request handling with automatic error translation and retry logic.

Provides specialized tools for scheduling campaign budget changes at specific times or dates, enabling time-based budget optimization strategies. Implements scheduling logic that queues budget update requests to execute at specified timestamps, supporting use cases like increasing budgets before peak shopping hours or reducing spend during low-performance periods. Integrates with campaign update tools to apply scheduled budget changes without manual intervention.

Exposes tools for creating and managing ad sets (campaign sub-units) with sophisticated audience targeting including demographic filters, interest-based targeting, custom audiences, lookalike audiences, and behavioral targeting. Implements targeting configuration through structured parameters that map to Meta's Targeting API, supporting age ranges, genders, locations, interests, and custom audience IDs. Ad sets define budget allocation and bidding strategy within campaigns.

Exposes tools for creating individual ads within ad sets, managing creative assets (images, videos, text), and configuring ad-level settings like headlines, descriptions, call-to-action buttons, and landing page URLs. Implements creative management through asset upload/reference mechanisms, supporting image URLs, video URLs, and text content. Ads represent the actual promotional content shown to users and inherit budget/targeting from parent ad set.

Provides specialized tools for duplicating existing campaigns or ad sets, automatically cloning all configuration (budget, targeting, creative assets) to create new instances. Supports optional parameter overrides (e.g., duplicate campaign but with different budget or name), enabling rapid campaign scaling and A/B testing setup. Duplication logic handles nested relationships (campaign → ad sets → ads) to ensure complete configuration cloning.

Exposes tools for retrieving campaign, ad set, and ad performance metrics including impressions, clicks, spend, conversions, cost-per-action, ROAS, and engagement metrics. Supports filtering by date range, breakdown dimensions (age, gender, location, placement, device), and custom metrics. Implements analytics through Meta's Insights API with automatic metric aggregation and time-series data retrieval. Returns structured JSON with performance data suitable for AI analysis and optimization recommendations.

Provides tools for researching available targeting options including interest categories, demographic ranges, location targeting, and audience size estimation. Implements audience research through Meta's Targeting Search API, returning available interests, locations, and demographic segments with estimated audience sizes. Enables AI assistants to discover targeting capabilities and estimate reach before creating ad sets, supporting informed audience selection decisions.