MCP Server Overview

The AdsMAA MCP Server is a bridge between your Meta Ads data and AI tools like Claude, Cursor, and VS Code. Using the open Model Context Protocol (MCP) standard by Anthropic, it lets you manage campaigns, analyze performance, run audits, and generate ad copy — all through natural language.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data. Think of it as a USB port for AI — plug in the AdsMAA MCP server, and your AI assistant instantly gains 180 tools for managing Meta Ads, including the latest Marketing API v23 surfaces (Advantage+ Suite, Advantage+ Creative AI, Threads ads, Business AI).

Supported AI Clients:

• Claude Desktop — Anthropic's desktop app
• Claude Code — CLI tool for developers
• Cursor — AI-powered code editor
• VS Code — Via MCP extensions
• Any MCP-compatible client

Architecture

output
Your AI Assistant (Claude, Cursor, VS Code)
        |
        v
  AdsMAA MCP Server (180 tools, rate-limited)
        |
        +-- AdsMAA Backend API (51 tools)
        |       |
        |       +-- PostgreSQL (synced data, audit reports, AI insights)
        |       +-- AI Engine (audit, autopilot, copy generation)
        |
        +-- Live Meta Proxy (~99 tools — read, write, creatives, videos, audiences, catalogs, rules, more)
        |       |
        |       +-- Meta Graph API v23 (real-time via stored OAuth tokens)
        |
        +-- v23 surface (30 tools — Advantage+ Suite, Advantage+ Creative AI,
                 CTWA + WhatsApp Flows, Threads/IG publishing, Business AI,
                 measurement, ASC/AAC migration scan, version info)

The key design principle: all Meta API access goes through AdsMAA. When you connect your Meta ad account via OAuth in the AdsMAA dashboard, the MCP server uses that same connection. No separate Meta tokens or credentials needed.

Tool Categories

The MCP server provides 180 tools across 26 categories (20 base + 6 v23 additions):

v23 additions (May 2026)

The most recent 30 tools wrap features Meta shipped in Marketing API v22-v25. Highlights:

• output

  meta_scan_legacy_campaigns

  — Finds Advantage+ Shopping (ASC) and Advantage+ App (AAC) campaigns across all your connected Meta integrations, sorted by recent spend, with the recommended replacement tool per campaign. Critical before the May 19, 2026 deadline when Meta blocks create/update of these legacy types.
• output

  meta_api_version

  — Returns the resolved Meta API version + full deprecation calendar. Agents should call this before recommending features that depend on a specific version.
• output

  meta_deprecated_metrics

  — Manifest of Insights metrics removed since Oct 2024 (
  output

  unique_actions

  ,
  output

  cost_per_unique_action_type

  , etc.) with the new equivalents. Use before requesting insights to avoid silently-empty fields.
• output

  live_meta_create_advantage_sales_campaign

  /
  output

  _leads_campaign

  /
  output

  _app_campaign

  — Unified Advantage+ objectives that replace the legacy ASC/AAC paths.
• output

  live_meta_advantage_creative_image_variants

  /
  output

  _text_variants

  /
  output

  _background_gen

  — AI generation surfaces. Video gen and dubbing are Beta (allowlist required).
• output

  live_meta_set_incremental_attribution

  — +20-24% incremental conversions in Meta's tests vs last-click.

See Meta API v23.0: What's New and ASC/AAC Migration Guide for the full picture.

Stored Data vs Live Data

The MCP server offers two ways to access your Meta Ads data:

AdsMAA Stored Data (51 tools)

These tools query data from AdsMAA's database — campaigns, metrics, and insights that were synced from Meta.

Advantages:

• Fast responses (local database queries)
• Includes AI features (health scores, audit reports, recommendations)
• Supports analytics not available directly from Meta (trends, comparisons, pacing)
• No Meta API rate limit impact

When to use: Day-to-day campaign management, audits, analytics, AI features

Live Meta API (129 tools)

Tools prefixed with

live_

Advantages:

• Always up-to-date (real-time from Meta)
• See changes immediately after making them
• Access to data not yet synced

When to use: Checking latest status, verifying recent changes, accessing data between syncs

Example workflow:

1. Use
   output

   meta_list_integrations

   to get your integration ID
2. Use
   output

   live_meta_campaigns

   for real-time campaign data
3. Use
   output

   meta_audit_account

   for AI-powered analysis of stored data

Security

• Token Isolation: The MCP server never has direct access to Meta OAuth tokens. All token decryption happens inside the AdsMAA backend.
• AES-256-GCM Encryption: Meta tokens are encrypted at rest in the database.
• API Key Auth: MCP server authenticates via API keys with scoped permissions.
• Organization Scoping: All data access is scoped to the authenticated user's organization.
• Rate Limiting: Built-in sliding-window rate limiter prevents API abuse.

Rate Limiting

The MCP server includes automatic rate limiting:

ADSMAA_RATE_LIMIT

ADSMAA_RATE_WINDOW_MS

When the limit is hit, requests are automatically delayed until capacity is available. Throttle events are logged to help with debugging.