Back to packageRELEASE DETAILS

1.0.0

PyPI

adiffy-meta-ads-mcp

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

Published7 Mar 2026

Direct dependencies9

Transitive dependenciesNot calculated

README

Version 1.0.0 documentation

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:

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

License

MIT License — see LICENSE for details.

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 9

Native requirements

9 direct targetsNot calculated transitive count

Package / target	Requirement	Relationship
httpx Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`httpx>=0.26.0`	runtime
mcp Environment { "extras": "cli", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`mcp[cli]==1.12.2`	runtime
pathlib Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pathlib>=1.0.1`	runtime
pillow Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pillow>=10.0.0`	runtime
python-dateutil Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`python-dateutil>=2.8.2`	runtime
python-dotenv Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`python-dotenv>=1.1.0`	runtime
requests Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`requests>=2.32.3`	runtime
pytest-asyncio Environment { "extras": "", "marker": "extra == \"test\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pytest-asyncio>=1.0.0; extra == "test"`	runtime
pytest Environment { "extras": "", "marker": "extra == \"test\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pytest>=8.4.1; extra == "test"`	runtime