Metadata-Version: 2.4
Name: adiffy-meta-ads-mcp
Version: 1.0.0
Summary: Adiffy Meta Ads MCP Server — Model Context Protocol server for Meta Ads API
Project-URL: Homepage, https://github.com/adiffy/meta-ads-mcp
Project-URL: Bug Tracker, https://github.com/adiffy/meta-ads-mcp/issues
Author: Adiffy Team
License: MIT
License-File: LICENSE
Keywords: adiffy,ads,api,facebook,mcp,meta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.26.0
Requires-Dist: mcp[cli]==1.12.2
Requires-Dist: pathlib>=1.0.1
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: requests>=2.32.3
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'test'
Requires-Dist: pytest>=8.4.1; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
# 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

```bash
# Install with pip
pip install -e .

# Or with uv
uv pip install -e .
```

### Running

```bash
# 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

```bash
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`):

```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](LICENSE) for details.
