TASKS.md

TASKS.md - Meta Ads MCP Server

Status Legend

• [ ] — Not started (Backlog / Ready)
• [~] — In progress
• [x] — Done
• [!] — Blocked

GitHub Project: Meta Ads MCP

---

Phase 1: Foundation

• #1 Project scaffold — pyproject.toml, directory structure, .gitignore, .env.example
• #2 Poetry environment with all dependencies
• #3 config.py — MetaAdsConfig, env var loading, multi-account support
• #4 client.py — MetaAdsClient wrapping SDK, async-compatible via to_thread, error handling
• #5 models.py — Pydantic v2 models (AdAccount, Campaign, AdSet, Ad, AdCreative, InsightRow, CustomAudience)
• #6 server.py skeleton — FastMCP init, lifespan, stdio transport, main entry point
• #7 formatting.py — base markdown formatters for all entity types

Phase 2: Read Tools

Accounts

• #8 get_ad_accounts — list accessible ad accounts
• #9 get_account_info — detailed account info

Campaigns

• #10 list_campaigns — list with status filtering
• #11 get_campaign — detailed campaign info

Ad Sets

• #12 list_ad_sets — list with campaign filter
• #13 get_ad_set — detailed ad set info with targeting

Ads

• #14 list_ads — list with ad set/campaign filter
• #15 get_ad — detailed ad info with creative reference

Insights

• #16 get_insights — flexible date/breakdowns/level query
• #17 get_campaign_insights — campaign performance with period comparison
• #18 get_account_insights — account-level performance metrics
• #19 compare_performance — compare entities side-by-side
• #20 get_breakdown_report — age/gender/placement/device breakdowns

Creatives

• #21 list_creatives — list ad creatives
• #22 get_creative — creative details with thumbnail and body

Audiences

• #23 list_audiences — custom and lookalike audiences
• #24 get_audience — audience details, size, status

Testing

• #25 Unit tests for all read tools with mocked fixtures

Phase 3: Write Tools

• #26 create_campaign — defaults PAUSED, dry_run support
• #27 update_campaign — name, budget, status, schedule
• #28 create_ad_set — targeting, budget, schedule, bid strategy
• #29 update_ad_set — targeting, budget, status, schedule
• #30 create_ad — with creative reference
• #31 update_ad_status — pause/activate/archive
• #32 Unit tests for all write tools

Phase 5: SDK v25 Features

Diagnostics

• #42 get_campaign_diagnostics — campaign-level diagnostic scores
• #43 get_ad_set_diagnostics — ad set quality/engagement/conversion scores
• #44 get_ad_diagnostics — ad relevance diagnostics

Enriched Models

• #45 Enrich CampaignModel with v25 fields (smart_promotion_type, budget_schedule_specs, etc.)
• #46 Enrich AdSetModel with v25 fields (frequency_control_specs, attribution_spec, etc.)
• #47 Enrich AdModel with v25 fields (conversion_specs, tracking_specs, etc.)
• #48 Enrich AdCreativeModel with v25 fields (asset_feed_spec, degrees_of_freedom_spec, etc.)
• #49 Enrich CustomAudienceModel with v25 fields (rule, data_source, retention_days, etc.)

Creative Write Tools

• #50 create_ad_creative — create ad creative with dry_run support
• #51 update_ad_creative — update creative fields

Advanced Features

• #52 Advantage+ campaign support (smart_promotion_type, spend_cap)
• #53 Frequency capping (frequency_control_specs on ad sets)
• #54 Attribution spec support on ad sets

Audience Creation Tools

• #55 create_custom_audience — website/app/customer file audiences
• #56 create_lookalike_audience — lookalike from source audience
• #57 Unit tests for all Phase 5 tools and models

Phase 4: Polish

• #33 Comprehensive error handling for Meta API errors (rate limits, permissions, invalid params)
• #34 Pagination support across all list tools (skipped)
• #35 Date range presets for insights
• #36 End-to-end testing (Claude Desktop config, MCP Inspector)
• #37 README finalization with usage examples

Phase 6: Asset Upload

• #65 AdImageModel and AdVideoModel Pydantic models
• #66 Client methods for image/video operations
• #67 Formatters for image/video display
• #68 Asset upload and listing tools (6 tools)
• #69 Unit tests for asset tools
• #70 Update project docs for Phase 6

Backlog / Future

• #40 Persistent Meta access token — system user token (non-expiring)
• Creative upload tools (image/video asset upload) — completed in Phase 6
• Bulk operations (batch status changes, batch budget updates)
• Trend analysis / ROAS tracking tools
• SSE transport for remote hosting
• Automated reporting (scheduled insight summaries)