Armavita Meta Ads Mcp

Created By
EfrainTorres4 months ago
Overview

Meta, Instagram, Facebook Ads MCP

ArmaVita Meta Ads MCP hero image

Brought to you by ArmaVita.com

Need a custom implementation? Contact us.

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

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.

Server Config

{
  "mcpServers": {
    "meta-ads-armavita": {
      "command": "bash",
      "args": [
        "/absolute/path/to/armavita-meta-ads-mcp/run.sh"
      ],
      "env": {
        "META_ACCESS_TOKEN": "<YOUR_META_ACCESS_TOKEN>"
      }
    }
  }
}
Project Info
Created At
4 months ago
Updated At
3 months ago
Author Name
EfrainTorres
Star
-
Language
-
License
-
Category
Tags

Recommend Servers

View All
Wpnews

a day ago