adiffy-meta-ads-mcp 1.0.0

Adiffy Meta Ads MCP Server — Model Context Protocol server for Meta Ads API

Adiffy Meta Ads MCP Server

Model Context Protocol (MCP) server for Meta Ads API

Provides 29+ tools for managing Meta (Facebook/Instagram) advertising campaigns through any MCP-compatible client.

Features

• Account Management — List ad accounts, get account details
• Campaign Operations — Create, read, update campaigns
• Ad Set Management — Manage targeting, budgets, schedules
• Ad Management — Create/edit ads with creatives
• Insights & Reporting — Performance metrics with breakdowns
• Targeting — Interest search, audience estimation, demographics
• Creative Management — Preview ad creatives and images
• Budget Schedules — Automated budget management
• Ads Library — Search Meta's Ad Library

Quick Start

Prerequisites

• Python 3.10+
• Meta App credentials (META_APP_ID, META_APP_SECRET)
• Meta API access token (META_ACCESS_TOKEN)

Environment Variables

# Required
export META_APP_ID="your_meta_app_id"
export META_APP_SECRET="your_meta_app_secret"
export META_ACCESS_TOKEN="your_access_token"

# Optional
export META_ADS_ENABLE_REPORTS="1"          # Enable report generation
export META_ADS_DISABLE_CALLBACK_SERVER="1" # Disable local OAuth server
export META_ADS_DISABLE_LOGIN_LINK="1"      # Disable login link tool

Installation

# Install with pip
pip install -e .

# Or with uv
uv pip install -e .

Running

# Default: stdio transport (for MCP clients like Claude Desktop)
adiffy-meta-ads-mcp

# HTTP transport (for web integrations)
adiffy-meta-ads-mcp --transport streamable-http --port 8080

# Login only
adiffy-meta-ads-mcp --login

Docker

docker build -t adiffy-meta-ads-mcp .
docker run -e META_APP_ID="..." -e META_APP_SECRET="..." -e META_ACCESS_TOKEN="..." adiffy-meta-ads-mcp

MCP Client Configuration

Add to your MCP client config (e.g., mcp_config.json):

{
  "meta-ads": {
    "command": "adiffy-meta-ads-mcp",
    "env": {
      "META_APP_ID": "your_app_id",
      "META_APP_SECRET": "your_app_secret",
      "META_ACCESS_TOKEN": "your_token"
    }
  }
}

Available Tools

Tool	Description
get_ad_accounts	List all accessible ad accounts
get_account_info	Get details for a specific account
get_campaigns	List campaigns with filtering
get_campaign_details	Get campaign details and metrics
create_campaign	Create a new campaign
get_adsets	List ad sets with filtering
get_adset_details	Get ad set details
update_adset	Update ad set settings
get_ads	List ads with filtering
get_ad_details	Get ad details
get_ad_creatives	Get creative details for ads
get_creative_details	Get specific creative details
get_ad_image	Download ad creative images
update_ad	Update ad settings
get_insights	Get performance insights
search_interests	Search for targeting interests
get_interest_suggestions	Get interest suggestions
estimate_audience_size	Estimate target audience size
search_behaviors	Search targeting behaviors
search_demographics	Search demographics
search_geo_locations	Search geographic locations
create_budget_schedule	Create budget schedules
get_login_link	Start OAuth authentication
search	OpenAI deep research search
fetch	OpenAI deep research fetch

Authentication

The server supports two authentication modes:

1. Direct Token (recommended for production): Set META_ACCESS_TOKEN environment variable
2. Local OAuth (for development): Uses a local callback server to handle the Meta OAuth flow

License

MIT License — see LICENSE for details.