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
2. Step 1: Prerequisites & Credentials
3. Step 2: Local Installation
4. Step 3: Registering with Antigravity IDE
5. Step 4: Registering with Claude Desktop
6. Step 5: Verifying the Connection
7. 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.
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.
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:

   cd C:\Users\prala\.gemini\antigravity-ide\scratch\meta-ads-mcp
   

2. Create a virtual environment:

   python -m venv venv
   

3. Install required packages:

   .\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:

   # 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:

   .\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:

   .\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:

.\venv\Scripts\python test_client.py

Expected Output:

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:

.\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:

   .\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.