# Meta Ads MCP Server

A Model Context Protocol (MCP) server built with Python and `fastmcp` to integrate Meta Ads (Facebook Ads) Graph API directly with AI coding assistants (like Antigravity and Claude Desktop).

This server maps Meta Ads API calls directly to easy-to-use, semantic tools for account discovery, campaign/adset/ad creation, custom audiences, status updates, campaign performance queries, placement breakdowns, demographic breakdowns, video retention analysis, and statistical A/B significance testing.

---

## 📋 Table of Contents
1. [Features & Tool Directory](#-features--tool-directory)
2. [Step 1: Prerequisites & Credentials](#-step-1-prerequisites--credentials)
3. [Step 2: Local Installation](#-step-2-local-installation)
4. [Step 3: Registering with Antigravity IDE](#-step-3-registering-with-antigravity-ide)
5. [Step 4: Registering with Claude Desktop](#-step-4-registering-with-claude-desktop)
6. [Step 5: Verifying the Connection](#-step-5-verifying-the-connection)
7. [Step 6: Pushing to GitHub](#-step-6-pushing-to-github)

---

## 🛠️ Features & Tool Directory

The server exposes **21 semantic tools** categorized into 5 main groups:

### 1. Account Discovery
*   `list_accounts`: Lists all accessible Facebook ad accounts including IDs, names, statuses, currencies, and total spent.

### 2. Performance Reporting (Level-specific & Segmented)
All reporting tools support outputting results as a Markdown **Table** (default), **CSV**, or raw **JSON**.
*   `get_campaign_performance`: Fetch campaign-level insights (impressions, clicks, CTR, spend, CPC, conversions, conversion values).
*   `get_adset_performance`: Fetch adset-level performance details.
*   `get_ad_performance`: Fetch ad-level performance and creative insights.
*   `get_device_performance`: Segment campaign performance by device platform (mobile, desktop, etc.).
*   `get_geo_performance`: Segment campaign performance by country.
*   `get_placement_performance`: Segment performance by publisher platform (Facebook/Instagram), placement position (Feeds/Stories), and device platform.
*   `get_demographic_performance`: Segment campaign performance by age and gender demographics.
*   `get_video_performance`: Fetch detailed video-specific plays, average watch time, and watched retention milestones (25%, 50%, 75%, 95%, 100% video completions).
*   `get_creative_report`: Merges ad creative details (title, body, text copy, image thumbnail) with performance metrics.

### 3. Audiences & Forms Management
*   `list_custom_audiences`: List remarketing lists, customer list audiences, and website pixel audiences.
*   `create_lead_form`: Create Meta Lead Generation Instant Forms on a Facebook Page.

### 4. Advanced Analytics & A/B Testing
*   `analyze_cross_campaign_performance`: Runs cross-campaign health checks, details best/worst performing campaigns, and suggests concrete budget reallocation or creative refresh strategies.
*   `analyze_ab_test`: Conducts statistical z-score calculations comparing CTR, CVR, and CPA between two campaigns (control vs variation) and indicates statistical significance (90%, 95%, 99% confidence levels).

### 5. Campaign & Creative Creations
*   `create_campaign`: Create new campaigns (supports objectives like `OUTCOME_TRAFFIC`, `OUTCOME_SALES`, `OUTCOME_LEADS`, `OUTCOME_AWARENESS`, `OUTCOME_ENGAGEMENT`, `OUTCOME_APP_PROMOTION`).
*   `create_adset`: Create adsets containing schedules, optimization goals, targeting specs, and budgets.
*   `create_ad_creative`: Prepare ad creative layouts linked to a page.
*   `create_ad`: Spin up ads under your adsets with your creatives.

### 6. Status Mutation
*   `update_campaign_status`: Activate (`ACTIVE`) or pause (`PAUSED`) campaigns.
*   `update_adset_status`: Activate or pause adsets.
*   `update_ad_status`: Activate or pause ads.

---

## 🔑 Step 1: Prerequisites & Credentials

To use the Meta Ads MCP Server, you need to obtain credentials from the Meta Developer platform.

### 1.1 Generate a Facebook Access Token
1. Go to the [Meta for Developers Portal](https://developers.facebook.com/).
2. Create a new App (choose **Business** or **Other** depending on your business requirements).
3. Set up the **Marketing API** product inside the app dashboard.
4. Navigate to **Marketing API** -> **Tools**.
5. Select the required permissions:
   *   `ads_read`
   *   `ads_management`
   *   `business_management`
6. Click **Generate Token** and copy the access token.

### 1.2 Locate Ad Account ID
1. Navigate to your [Meta Ads Manager](https://adsmanager.facebook.com/).
2. In the account dropdown, copy the 15-digit Ad Account ID (e.g. `123456789012345`).

---

## 💻 Step 2: Local Installation

1. Navigate to the project directory:
   ```bash
   cd C:\Users\prala\.gemini\antigravity-ide\scratch\meta-ads-mcp
   ```

2. Create a virtual environment:
   ```bash
   python -m venv venv
   ```

3. Install required packages:
   ```bash
   .\venv\Scripts\pip install -r requirements.txt
   ```

4. Create your `.env` credentials file by creating a file named `.env` in the root of the project directory with the following contents:
   ```env
   # Meta Graph API Credentials
   META_ADS_ACCESS_TOKEN=EACJye51NVHcBO6... (your token)
   META_ADS_AD_ACCOUNT_ID=act_1234567890... (your ad account ID, optional)
   ```

---

## ⚙️ Step 3: Registering with Antigravity IDE

To integrate the Meta Ads MCP Server directly with your Google Antigravity IDE assistant:

1. Ensure your `.env` file is populated with your active Meta credentials.
2. Execute the registration script inside your virtual environment:
   ```bash
   .\venv\Scripts\python configure_antigravity_mcp.py
   ```
3. This script will read credentials from `.env` and configure them inside the Antigravity global configuration file (`C:\Users\prala\.gemini\config\mcp_config.json`).
4. **Restart your Antigravity IDE** (or rebuild your agent connections) to load the new server. You will see 21 tools prefixed with `mcp_meta-ads_*` registered.

---

## ⚙️ Step 4: Registering with Claude Desktop

To use the connector locally with your Claude Desktop client:

1. Execute the local registration script:
   ```bash
   .\venv\Scripts\python configure_local_mcp.py
   ```
2. The script will write your local `.env` and automatically add the `meta-ads` server block into your Claude Desktop configuration file (`%APPDATA%\Claude\claude_desktop_config.json`).
3. **Restart your Claude Desktop App** to apply the configuration.

---

## 🧪 Step 5: Verifying the Connection

You can verify that the server is functional and authenticating correctly with the Meta API:

### 5.1 Run the Automated Test Client
Run the verification script to confirm all 21 tools are successfully registered in FastMCP:
```bash
.\venv\Scripts\python test_client.py
```
*Expected Output:*
```text
Importing Meta Ads MCP Server...
Successfully loaded MCP Server!
Server Name: Meta Ads MCP Server

Checking registered MCP tools:
1. Tool name: list_accounts
   Description: List all Meta Ad Accounts accessible...
...
21. Tool name: analyze_ab_test
   Description: Perform a statistical A/B test analysis...

Total Tools Registered: 21
Dry-run validation PASSED: Server script compiles and registers all endpoints successfully.
```

### 5.2 Test Active Account Fetching
Verify that your access token is valid and can retrieve real data:
```bash
.\venv\Scripts\python -c "import server; print(server.list_accounts())"
```
This should print a JSON array listing all your active ad accounts, their status codes, and currency configurations.

---

## 📤 Step 6: Pushing to GitHub

To push the codebase and documentations to your remote GitHub repository:

1. Go to your GitHub account (`pralayasimha23`).
2. Create a new public/private repository named **`meta-ads-mcp`**.
3. Run the automated Git push script:
   ```bash
   .\venv\Scripts\python push_to_github.py
   ```
This script will initialize Git, commit all code, configure the remote origin, and push the repository to `https://github.com/pralayasimha23/meta-ads-mcp.git`.