Overview

The Facebook Ads MCP tools enables seamless access to Facebook's advertising platform data and management capabilities. This server provides a comprehensive suite of tools for retrieving advertising insights, managing campaigns, and accessing creative assets through Facebook's Graph API.

Key Benefits:

• Complete Ad Account Management: Access and manage all your Facebook ad accounts from a single interface

• Real-time Performance Data: Retrieve comprehensive advertising metrics and insights

• Creative Asset Access: Extract and analyze ad creatives including images, videos, and text

• Activity Monitoring: Track changes and updates across your advertising accounts

Tool Reference

1. List Ad Accounts

Purpose: Discover and list all Facebook ad accounts accessible with your credentials.

What it does: Retrieves a complete list of all ad accounts you have access to, providing essential account information including names and IDs.

Key Parameters:

• No required parameters - automatically discovers all accessible accounts

Sample Use Cases:

• Initial setup to discover available ad accounts

• Account auditing and access verification

• Building account selection interfaces

Example Output:

{
  "data": [
    {
      "id": "act_1234567890",
      "name": "My Business - Main Account"
    },
    {
      "id": "act_9876543210", 
      "name": "My Business - Test Account"
    }
  ]
}

2. Get Ad Account Details

Purpose: Retrieve comprehensive information about a specific Facebook ad account.

What it does: Fetches detailed account information including business details, account status, spending limits, currency settings, and account creation date.

Key Parameters:

• act_id (required): The ad account ID (e.g., "act_1234567890")

• fields (optional): Specific data fields to retrieve

Available Fields:

• name: Account display name

• business_name: Associated business name

• account_status: Current account status

• balance: Account balance

• amount_spent: Total amount spent

• currency: Account currency

• created_time: Account creation date

Sample Use Cases:

• Account health monitoring

• Financial tracking and budget management

• Account setup verification

Example Request:

Example Output:

{
  "id": "act_1234567890",
  "name": "My Business - Main Account",
  "account_status": 1,
  "balance": "5000",
  "currency": "USD"
}

3. Get Ad Account Insights

Purpose: Retrieve comprehensive performance metrics and analytics for your advertising campaigns.

What it does: Provides detailed advertising performance data including impressions, clicks, conversions, costs, and return on ad spend (ROAS). This is the primary tool for analyzing campaign effectiveness.

Key Parameters:

• act_id (required): The ad account ID

• fields (required): Performance metrics to retrieve

• date_preset (optional): Predefined time period (default: last_30d)

• time_range (optional): Custom date range

• level (optional): Data aggregation level (account, campaign, adset, ad)

Popular Performance Fields:

• impressions: Number of times ads were shown

• clicks: Number of clicks on ads

• spend: Amount spent on advertising

• cpc: Cost per click

• cpm: Cost per thousand impressions

• ctr: Click-through rate

• reach: Number of unique people reached

• conversions: Number of conversions

• purchase_roas: Return on ad spend

Time Period Options:

• today, yesterday

• last_7d, last_30d, last_90d

• this_month, last_month

• this_quarter, last_quarter

Sample Use Cases:

• Daily performance monitoring

• Campaign ROI analysis

• Budget optimization decisions

• Performance reporting

Example Request:

Example Output:

{
  "data": [
    {
      "impressions": "125000",
      "clicks": "2500", 
      "spend": "750.00",
      "cpc": "0.30",
      "conversions": [{"action_type": "purchase", "value": "85"}],
      "purchase_roas": [{"action_type": "omni_purchase", "value": "3.2"}],
      "date_start": "2024-01-01",
      "date_stop": "2024-01-30"
    }
  ]
}

4. Get Account Activities

Purpose: Monitor and track all changes and updates made to your ad account and campaigns.

What it does: Provides a detailed audit trail of account activities including campaign modifications, budget changes, ad creation/deletion, and targeting updates.

Key Parameters:

• act_id (required): The ad account ID

• fields (optional): Activity details to retrieve

• time_range (optional): Date range for activities

• limit (optional): Number of activities per page (max 100)

Activity Fields:

• actor_name: Person who made the change

• event_time: When the change occurred

• object_type: Type of object changed (AD, CAMPAIGN, ADSET)

• object_name: Name of the changed object

• translated_event_type: Human-readable description

• changed_data: Specific details of what changed

Sample Use Cases:

• Account security monitoring

• Change tracking and auditing

• Team collaboration oversight

• Troubleshooting campaign issues

Example Request:

Example Output:

{
  "data": [
    {
      "actor_name": "John Smith",
      "event_time": "2024-01-15T14:30:00+0000",
      "object_type": "CAMPAIGN",
      "object_name": "Summer Sale Campaign",
      "translated_event_type": "campaign budget updated"
    }
  ]
}

5. Get Creative Assets

Purpose: Extract and analyze the creative elements (images, videos, text) used in your advertisements.

What it does: Retrieves comprehensive creative asset information for any ad, including media URLs, ad copy, headlines, call-to-action buttons, and destination links.

Key Parameters:

• ad_id (required): The specific ad ID to analyze

Retrieved Asset Information:

• Media Assets: Direct URLs to images or videos

• Text Content: Ad headlines, body text, descriptions

• Interactive Elements: Call-to-action button types

• Destination: Landing page URLs

• Asset Type: Automatic detection (image/video)

Sample Use Cases:

• Creative performance analysis

• Asset library management

• Competitor research and inspiration

• A/B testing preparation

• Creative compliance checking

Example Request:

Example Output:

{
  "assetUrl": "https://scontent.xx.fbcdn.net/v/abc123.jpg",
  "assetType": "image",
  "title": "Limited Time Offer - 50% Off",
  "body": "Don't miss out on our biggest sale of the year! Shop now and save big on all your favorite items.",
  "linkUrl": "https://mystore.com/sale",
  "callToActionType": "SHOP_NOW",
  "error": null
}

6. Fetch Pagination Results

Purpose: Automatically retrieve complete datasets when Facebook returns paginated results.

What it does: Seamlessly handles Facebook's pagination system to ensure you receive all available data, not just the first page of results.

Key Parameters:

• url (required): The pagination URL from a previous API response

Automatic Behavior: This tool is typically called automatically by other tools when they encounter paginated results. You generally won't need to use this tool directly.

Sample Use Cases:

• Large dataset retrieval

• Complete account auditing

• Comprehensive reporting

• Historical data analysis

Getting Started

Prerequisites

• Active Facebook Business account

• Facebook App with appropriate permissions

• Valid access tokens for the Facebook Graph API

Basic Workflow

1. Discovery: Start with "List Ad Accounts" to see available accounts

2. Account Analysis: Use "Get Ad Account Details" for account information

3. Performance Review: Retrieve insights with "Get Ad Account Insights"

4. Creative Analysis: Examine ad creatives with "Get Creative Assets"

5. Activity Monitoring: Track changes with "Get Account Activities"

Best Practices

Data Retrieval:

• Use appropriate date ranges to avoid overwhelming data volumes

• Select only necessary fields to improve response times

• Take advantage of automatic pagination for complete datasets

Performance Monitoring:

• Establish regular reporting schedules

• Set up alerts for significant performance changes

• Compare performance across different time periods

Support and Troubleshooting

Common Issues

Authentication Errors: Verify your Facebook access tokens are valid and have appropriate permissions.

Data Limits: Facebook APIs have rate limits. The server handles these automatically, but extremely high-volume usage may experience delays.

Missing Data: Some metrics may not be available for certain campaign types or time periods.

Error Handling

The server provides detailed error messages including:

• Facebook API error codes and descriptions

• Suggested resolution steps

• Alternative approaches when available

All tools include automatic error handling and will return structured error information to help diagnose and resolve issues quickly.