Meta, Instagram, Facebook Ads MCP

armavita-meta-ads-mcp is a local Model Context Protocol server for Meta Ads. It is built for local MCP clients (Claude Code, Cursor, Codex) and supports:

• Meta access token auth (META_ACCESS_TOKEN)
• Local OAuth flow (META_APP_ID + META_APP_SECRET)
• stdio MCP transport only
• Python 3.11+
• mcp[cli]==1.26.0
• Meta Marketing API v25.0 by default (META_GRAPH_API_VERSION override supported)

Current contract version: 1.1.0.

Install

From PyPI (once published):

pip install armavita-meta-ads-mcp

From source (recommended during development):

uv sync

Run

armavita-meta-ads-mcp

Module entrypoint:

python -m armavita_meta_ads_mcp

Login flow:

armavita-meta-ads-mcp --login

Quick MCP Client Config

Minimal MCP server registration (JSON format used by many clients):

{
  "mcpServers": {
    "meta-ads-armavita": {
      "command": "armavita-meta-ads-mcp",
      "env": {
        "META_ACCESS_TOKEN": "EA...",
        "META_GRAPH_API_VERSION": "v25.0"
      }
    }
  }
}

OAuth mode (no direct token in config):

{
  "mcpServers": {
    "meta-ads-armavita": {
      "command": "armavita-meta-ads-mcp",
      "env": {
        "META_APP_ID": "YOUR_APP_ID",
        "META_APP_SECRET": "YOUR_APP_SECRET"
      }
    }
  }
}

Then run once to complete login:

armavita-meta-ads-mcp --login

Tool Coverage

• Accounts: list_ad_accounts, read_ad_account
• Campaigns: list_campaigns, read_campaign, create_campaign, update_campaign
• Budget schedules: create_campaign_budget_schedule
• Ad sets: list_ad_sets, read_ad_set, create_ad_set, update_ad_set
• Ads/creatives/media: list_ads, read_ad, list_ad_previews, create_ad, update_ad, list_ad_creatives, read_ad_creative, create_ad_creative, update_ad_creative, upload_ad_image_asset, read_ad_image, export_ad_image_file, search_pages, list_account_pages
• Insights/reporting: list_insights, create_report
• Targeting: search_interests, suggest_interests, estimate_audience_size, search_behaviors, search_demographics, search_geo_locations
• Duplication: clone_campaign, clone_ad_set, clone_ad, clone_ad_creative
• Ads Library: search_ads_archive
• Research helpers: search_web_content, read_web_content

Pagination

Cursor-based pagination is supported on core list/read streams:

• list_ad_accounts, list_campaigns, list_ad_sets, list_ads, list_insights
• list_ad_creatives, search_interests, suggest_interests, search_behaviors, search_demographics, search_geo_locations, search_ads_archive
• Use page_cursor with the paging.cursors.after value from the previous response.
• Responses preserve Meta's native paging object.

Insights Query Notes

• list_insights and create_report support either:
  • date_range as { "since": "YYYY-MM-DD", "until": "YYYY-MM-DD" }, or
  • date_range as a preset (for example last_30d, maximum).
• create_report.comparison_period uses the same format and validation as date_range.
• previous_30d is normalized to last_30d.
• For action metrics, use action_breakdowns (and optional summary_action_breakdowns) instead of mixing action keys into breakdowns.

Security

• Access tokens are redacted from URL fields returned by the server (including nested paging.next URLs).

Docs

• Authentication Setup Guide
• Local Client Guide
• Security Policy

Scope

• This repository is an OSS local MCP server.
• Transport mode is local stdio only.
• Tool aliases are intentionally not exposed.

License

GNU Affero General Public License v3.0 (AGPLv3). See LICENSE.