### Automated Setup

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Use the interactive setup script to configure the environment and dependencies.

```bash
# Clone the repository first
git clone https://github.com/wipsoft/meta-mcp.git
cd meta-ads-mcp

# Run the interactive setup
npm run setup
```

--------------------------------

### Install from Source

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Clone the repository and build the project manually.

```bash
git clone https://github.com/wipsoft/meta-mcp.git
cd meta-ads-mcp
npm install
npm run build
```

--------------------------------

### Run Example Client

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Execute the example client script using tsx.

```bash
npx tsx examples/client-example.ts
```

--------------------------------

### Install Meta Ads MCP

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Install the package globally using npm.

```bash
npm install -g meta-ads-mcp
```

--------------------------------

### Verify Setup

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Run the health check command to ensure the server is operational.

```bash
# Run health check to verify everything is working
npm run health-check
```

--------------------------------

### Node.js Installation Verification

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Commands to verify Node.js, npm, and npx installations.

```bash
# Install Node.js if not installed
# macOS: brew install node
# Windows: Download from nodejs.org
# Linux: Use your package manager

# Verify installation
node --version
npm --version
npx --version
```

--------------------------------

### Verify Installation

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Run the health check command to ensure the server is configured correctly.

```bash
npm run health-check
```

--------------------------------

### Verify Meta Account Setup Tool Call

Source: https://context7.com/brijr/meta-mcp/llms.txt

Use this tool call to verify that a Meta ad account is properly configured for advertising. It checks account access, payment methods, and campaign status. The response indicates the overall setup status and details for each component.

```typescript
// MCP Tool Call
{
  "tool": "verify_account_setup",
  "arguments": {
    "account_id": "act_123456789"
  }
}
```

```typescript
// Response
{
  "account_id": "act_123456789",
  "setup_status": "ready",
  "components": {
    "account_access": {"status": "success", "details": "Account \"My Ad Account\" accessible"},
    "payment_method": {"status": "success", "details": "Payment method configured"},
    "active_campaigns": {"status": "success", "details": "Found 5 campaigns", "count": 5}
  },
  "recommendations": [],
  "warnings": []
}
```

--------------------------------

### Get Meta API Reference Tool Call

Source: https://context7.com/brijr/meta-mcp/llms.txt

Use this tool call to retrieve a reference guide for valid Meta Marketing API parameters, including optimization goals, billing events, and their valid combinations. The response provides available options and their valid pairings.

```typescript
// MCP Tool Call
{
  "tool": "get_meta_api_reference",
  "arguments": {}
}
```

```typescript
// Response
{
  "optimization_goals": {
    "description": "Available optimization goals for ad sets",
    "values": ["REACH", "IMPRESSIONS", "LINK_CLICKS", "LANDING_PAGE_VIEWS", "CONVERSIONS", "LEAD_GENERATION", "VIDEO_VIEWS"]
  },
  "billing_events": {
    "values": ["IMPRESSIONS", "LINK_CLICKS", "PAGE_LIKES", "THRUPLAY"]
  },
  "valid_combinations": {
    "combinations": [
      {"optimization_goal": "LINK_CLICKS", "billing_event": "IMPRESSIONS", "use_case": "Website traffic"},
      {"optimization_goal": "CONVERSIONS", "billing_event": "IMPRESSIONS", "use_case": "Conversions with pixel"},
      {"optimization_goal": "LEAD_GENERATION", "billing_event": "IMPRESSIONS", "use_case": "Lead forms"}
    ]
  },
  "campaign_objectives": {
    "OUTCOME_TRAFFIC": {
      "description": "Drive website traffic",
      "recommended_optimization": ["LINK_CLICKS", "LANDING_PAGE_VIEWS"],
      "requires_promoted_object": true
    }
  }
}
```

--------------------------------

### get_meta_api_reference

Source: https://context7.com/brijr/meta-mcp/llms.txt

Retrieves a reference guide for valid Meta Marketing API parameters, including optimization goals, billing events, and valid combinations.

```APIDOC
## POST get_meta_api_reference

### Description
Returns a reference guide for valid Meta Marketing API parameters including optimization goals, billing events, and their valid combinations.

### Method
POST

### Endpoint
get_meta_api_reference

### Response
#### Success Response (200)
- **optimization_goals** (object) - Available optimization goals for ad sets
- **billing_events** (object) - Available billing events
- **valid_combinations** (object) - Valid combinations of goals and events
- **campaign_objectives** (object) - Campaign objectives and recommended optimizations

#### Response Example
{
  "optimization_goals": {
    "description": "Available optimization goals for ad sets",
    "values": ["REACH", "IMPRESSIONS", "LINK_CLICKS", "LANDING_PAGE_VIEWS", "CONVERSIONS", "LEAD_GENERATION", "VIDEO_VIEWS"]
  },
  "billing_events": {
    "values": ["IMPRESSIONS", "LINK_CLICKS", "PAGE_LIKES", "THRUPLAY"]
  }
}
```

--------------------------------

### Get Token Info

Source: https://context7.com/brijr/meta-mcp/llms.txt

Retrieve information about the current access token, including its validity, expiration, and granted permissions. Useful for debugging authentication issues.

```typescript
// MCP Tool Call
{
  "tool": "get_token_info",
  "arguments": {}
}

// Response
{
  "token_info": {
    "isValid": true,
    "appId": "123456789",
    "userId": "987654321",
    "scopes": ["ads_management", "ads_read", "business_management"],
    "expiresAt": "2024-03-01T10:30:00.000Z"
  },
  "current_config": {
    "has_app_credentials": true,
    "auto_refresh_enabled": true,
    "token_expiration": "2024-03-01T10:30:00.000Z"
  },
  "token_status": {
    "is_valid": true,
    "is_expiring_soon": false,
    "requires_refresh": false
  },
  "recommendations": [
    "Token is valid and properly configured"
  ]
}
```

--------------------------------

### Get Ad Accounts MCP Tool Call and Response

Source: https://context7.com/brijr/meta-mcp/llms.txt

Use the 'get_ad_accounts' tool to retrieve all Meta ad accounts accessible with the current token. The response includes account details and total count.

```typescript
// MCP Tool Call
{
  "tool": "get_ad_accounts",
  "arguments": {}
}
```

```typescript
// Response
{
  "success": true,
  "accounts": [
    {
      "id": "act_123456789",
      "name": "My Ad Account",
      "account_status": 1,
      "currency": "USD",
      "timezone_name": "America/Los_Angeles",
      "balance": "0",
      "business": {
        "id": "987654321",
        "name": "My Business"
      }
    }
  ],
  "total_accounts": 1,
  "message": "Ad accounts retrieved successfully"
}
```

--------------------------------

### Get Insights

Source: https://context7.com/brijr/meta-mcp/llms.txt

Retrieves detailed performance metrics for campaigns, ad sets, or ads including impressions, clicks, spend, and conversion data.

```typescript
// MCP Tool Call
{
  "tool": "get_insights",
  "arguments": {
    "object_id": "23851234567890456",
    "level": "campaign",
    "date_preset": "last_30d",
    "fields": ["impressions", "clicks", "spend", "ctr", "cpc", "cpm", "reach"],
    "breakdowns": ["age", "gender"]
  }
}

// Response
{
  "insights": [
    {
      "date_start": "2024-01-01",
      "date_stop": "2024-01-30",
      "impressions": "125000",
      "clicks": "3750",
      "spend": "450.00",
      "reach": "85000",
      "ctr": "3.00",
      "cpc": "0.12",
      "cpm": "3.60"
    }
  ],
  "summary": {
    "total_impressions": 125000,
    "total_clicks": 3750,
    "total_spend": 450.00,
    "average_ctr": 3.00,
    "average_cpc": 0.12,
    "average_cpm": 3.60,
    "total_reach": 85000
  },
  "total_count": 1
}
```

--------------------------------

### verify_account_setup

Source: https://context7.com/brijr/meta-mcp/llms.txt

Verifies that a Meta ad account is properly configured for advertising, checking account access, payment methods, and campaign status.

```APIDOC
## POST verify_account_setup

### Description
Verifies that a Meta ad account is properly configured for advertising, checking account access, payment methods, and campaign status.

### Method
POST

### Endpoint
verify_account_setup

### Request Body
- **account_id** (string) - Required - The ID of the ad account to verify

### Request Example
{
  "account_id": "act_123456789"
}

### Response
#### Success Response (200)
- **account_id** (string) - The verified account ID
- **setup_status** (string) - The overall status of the account setup
- **components** (object) - Status details for access, payment, and campaigns

#### Response Example
{
  "account_id": "act_123456789",
  "setup_status": "ready",
  "components": {
    "account_access": {"status": "success", "details": "Account accessible"},
    "payment_method": {"status": "success", "details": "Payment method configured"}
  }
}
```

--------------------------------

### Run Test Suite

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Execute the project's test suite using npm.

```bash
npm test
```

--------------------------------

### Configure Optional Environment Variables

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Set optional configuration for OAuth, API versions, and debugging.

```bash
META_APP_ID=your_app_id                    # For OAuth
META_APP_SECRET=your_app_secret            # For OAuth
META_BUSINESS_ID=your_business_id          # For business-specific operations
META_API_VERSION=v23.0                     # API version (default: v23.0)
META_API_TIER=standard                     # 'development' or 'standard'
META_AUTO_REFRESH=true                     # Enable automatic token refresh
META_REFRESH_TOKEN=your_refresh_token      # For token refresh
META_MCP_REQUEST_TIMEOUT_MS=30000          # Request timeout in ms (0 to disable)
META_MCP_DEBUG=1                           # Enable verbose MetaApiClient debug logs
```

--------------------------------

### Configure Required Environment Variables

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Set the mandatory access token for authentication.

```bash
META_ACCESS_TOKEN=your_access_token_here
```

--------------------------------

### Configure Meta Ads MCP Environment Variables

Source: https://context7.com/brijr/meta-mcp/llms.txt

Configure the Meta Ads MCP server using these environment variables. Required variables include the Meta access token. Optional variables cover OAuth configuration, API settings, and token management for enhanced control and reliability.

```bash
# Required
META_ACCESS_TOKEN=your_access_token_here

# Optional - OAuth Configuration
META_APP_ID=your_app_id
META_APP_SECRET=your_app_secret
META_BUSINESS_ID=your_business_id
META_REDIRECT_URI=https://your-app.com/callback

# Optional - API Configuration
META_API_VERSION=v23.0
META_API_TIER=standard              # 'development' or 'standard'
META_MCP_REQUEST_TIMEOUT_MS=30000   # Request timeout in ms
META_MCP_DEBUG=1                    # Enable verbose debug logs

# Optional - Token Management
META_AUTO_REFRESH=true
META_REFRESH_TOKEN=your_refresh_token
```

--------------------------------

### Configure Claude Desktop for Meta Ads MCP

Source: https://context7.com/brijr/meta-mcp/llms.txt

Add Meta Ads MCP configuration to Claude Desktop's config file. Ensure to replace placeholder values with your actual Meta access token and optional app details.

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_APP_ID": "your_app_id_optional",
        "META_APP_SECRET": "your_app_secret_optional",
        "META_AUTO_REFRESH": "true",
        "META_API_VERSION": "v23.0"
      }
    }
  }
}
```

--------------------------------

### Local MCP Server Configuration

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Configuration block for local development using an absolute path to the build index.

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["/absolute/path/to/meta-ads-mcp/build/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}
```

--------------------------------

### Configure MCP Server

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

JSON configuration for Claude Desktop or Cursor. Use the basic version for standard tokens or the advanced version for OAuth and app secret requirements.

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_AUTO_REFRESH": "true",
        "META_BUSINESS_ID": "your_business_id"
      }
    }
  }
}
```

--------------------------------

### Create Campaign MCP Tool Call and Response

Source: https://context7.com/brijr/meta-mcp/llms.txt

Create a new Meta ad campaign with specified objective, name, and budget. The response confirms success and provides the new campaign ID and details.

```typescript
// MCP Tool Call
{
  "tool": "create_campaign",
  "arguments": {
    "account_id": "act_123456789",
    "name": "Summer Sale 2024",
    "objective": "OUTCOME_TRAFFIC",
    "status": "PAUSED",
    "daily_budget": 5000,
    "special_ad_categories": [],
    "bid_strategy": "LOWEST_COST_WITHOUT_CAP"
  }
}
```

```typescript
// Response
{
  "success": true,
  "campaign_id": "23851234567890456",
  "message": "Campaign \"Summer Sale 2024\" created successfully",
  "details": {
    "id": "23851234567890456",
    "name": "Summer Sale 2024",
    "objective": "OUTCOME_TRAFFIC",
    "status": "PAUSED",
    "account_id": "act_123456789"
  }
}
```

--------------------------------

### View MCP Logs

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Commands to view MCP server logs on different operating systems.

```bash
# macOS/Linux - View logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows - View logs
type "%APPDATA%\Claude\logs\mcp*.log"
```

--------------------------------

### check_campaign_readiness

Source: https://context7.com/brijr/meta-mcp/llms.txt

Validates if a campaign is ready for ad set creation.

```APIDOC
## check_campaign_readiness

### Description
Validates if a campaign is ready for ad set creation by checking status, objective requirements, and budget configuration.

### Request Body
- **campaign_id** (string) - Required

### Request Example
{
  "campaign_id": "23851234567890456"
}

### Response
#### Success Response (200)
- **campaign_id** (string)
- **is_ready** (boolean)
- **issues** (array)
- **recommendations** (array)

#### Response Example
{
  "campaign_id": "23851234567890456",
  "is_ready": true,
  "issues": [],
  "recommendations": [ ... ]
}
```

--------------------------------

### create_campaign

Source: https://context7.com/brijr/meta-mcp/llms.txt

Creates a new Meta ad campaign with specified objective, name, and budget configuration. Supports all campaign objectives including traffic, conversions, awareness, leads, and sales.

```APIDOC
## POST /brijr/meta-mcp/create_campaign

### Description
Creates a new Meta ad campaign with specified objective, name, and budget configuration. Supports all campaign objectives including traffic, conversions, awareness, leads, and sales.

### Method
POST

### Endpoint
/brijr/meta-mcp/create_campaign

### Parameters
#### Request Body
- **account_id** (string) - Required - The ID of the ad account where the campaign will be created.
- **name** (string) - Required - The name of the new campaign.
- **objective** (string) - Required - The objective of the campaign (e.g., 'OUTCOME_TRAFFIC', 'CONVERSIONS').
- **status** (string) - Optional - The initial status of the campaign (e.g., 'PAUSED', 'ACTIVE'). Defaults to 'PAUSED'.
- **daily_budget** (integer) - Optional - The daily budget for the campaign.
- **special_ad_categories** (array) - Optional - An array of special ad categories to assign to the campaign.
- **bid_strategy** (string) - Optional - The bidding strategy for the campaign (e.g., 'LOWEST_COST_WITHOUT_CAP').

### Request Example
```json
{
  "tool": "create_campaign",
  "arguments": {
    "account_id": "act_123456789",
    "name": "Summer Sale 2024",
    "objective": "OUTCOME_TRAFFIC",
    "status": "PAUSED",
    "daily_budget": 5000,
    "special_ad_categories": [],
    "bid_strategy": "LOWEST_COST_WITHOUT_CAP"
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the campaign creation was successful.
- **campaign_id** (string) - The unique identifier of the newly created campaign.
- **message** (string) - A confirmation message.
- **details** (object) - Details of the created campaign.
  - **id** (string) - The campaign ID.
  - **name** (string) - The campaign name.
  - **objective** (string) - The campaign objective.
  - **status** (string) - The campaign status.
  - **account_id** (string) - The ID of the ad account.

#### Response Example
```json
{
  "success": true,
  "campaign_id": "23851234567890456",
  "message": "Campaign \"Summer Sale 2024\" created successfully",
  "details": {
    "id": "23851234567890456",
    "name": "Summer Sale 2024",
    "objective": "OUTCOME_TRAFFIC",
    "status": "PAUSED",
    "account_id": "act_123456789"
  }
}
```
```

--------------------------------

### Remote MCP Configuration via mcp-remote

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Configuration for bridging HTTP to stdio using mcp-remote.

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-project.vercel.app/api/mcp",
        "--header",
        "Authorization:${META_AUTH_HEADER}"
      ],
      "env": {
        "META_AUTH_HEADER": "Bearer your_session_token_here"
      }
    }
  }
}
```

--------------------------------

### Create Ad Set Enhanced

Source: https://context7.com/brijr/meta-mcp/llms.txt

Creates a new ad set with advanced validation and configuration for targeting, optimization goals, and promoted objects.

```typescript
// MCP Tool Call
{
  "tool": "create_ad_set_enhanced",
  "arguments": {
    "campaign_id": "23851234567890456",
    "name": "US Women 30-50 Entrepreneurs",
    "daily_budget": 2500,
    "optimization_goal": "LINK_CLICKS",
    "billing_event": "IMPRESSIONS",
    "status": "PAUSED",
    "targeting": {
      "age_min": 30,
      "age_max": 50,
      "genders": [2],
      "geo_locations": {
        "countries": ["US"],
        "location_types": ["home", "recent"]
      },
      "interests": [
        {"id": "6003139266461", "name": "Entrepreneurship"}
      ]
    },
    "promoted_object": {
      "page_id": "123456789012345"
    }
  }
}

// Response
{
  "success": true,
  "ad_set_id": "23851234567891234",
  "message": "Ad set \"US Women 30-50 Entrepreneurs\" created successfully",
  "details": {
    "id": "23851234567891234",
    "name": "US Women 30-50 Entrepreneurs",
    "campaign_id": "23851234567890456",
    "optimization_goal": "LINK_CLICKS",
    "billing_event": "IMPRESSIONS",
    "status": "PAUSED"
  }
}
```

--------------------------------

### Check Campaign Readiness

Source: https://context7.com/brijr/meta-mcp/llms.txt

Validates if a campaign is ready for ad set creation by checking status, objective requirements, and budget configuration.

```typescript
// MCP Tool Call
{
  "tool": "check_campaign_readiness",
  "arguments": {
    "campaign_id": "23851234567890456"
  }
}

// Response
{
  "campaign_id": "23851234567890456",
  "campaign_name": "Summer Sale 2024",
  "objective": "OUTCOME_TRAFFIC",
  "status": "PAUSED",
  "is_ready": true,
  "issues": [],
  "requirements": [
    "Facebook Pixel may be required for conversion tracking"
  ],
  "recommendations": [
    "For OUTCOME_TRAFFIC, use optimization_goal: LINK_CLICKS or LANDING_PAGE_VIEWS",
    "Recommended billing_event: LINK_CLICKS or IMPRESSIONS",
    "Minimum daily budget: $1.00 (100 cents)"
  ]
}
```

--------------------------------

### Test MCP Server Manually

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Commands to test the MCP server execution directly.

```bash
# Test the MCP server directly
npx -y meta-ads-mcp

# Or if installed locally
node build/index.js
```

--------------------------------

### Web MCP Client Configuration

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Configuration for connecting to a remote MCP endpoint via URL.

```json
{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://your-project.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer your_session_token"
      }
    }
  }
}
```

--------------------------------

### upload_image_from_url

Source: https://context7.com/brijr/meta-mcp/llms.txt

Downloads an image from a URL and uploads it to Meta's servers, returning an image_hash.

```APIDOC
## upload_image_from_url

### Description
Downloads an image from a URL and uploads it to Meta's servers, returning an image_hash for use in creatives.

### Request Body
- **account_id** (string) - Required - The ID of the ad account.
- **image_url** (string) - Required - Source URL of the image.
- **image_name** (string) - Required - Name for the uploaded image.

### Request Example
{
  "account_id": "act_123456789",
  "image_url": "https://example.com/images/product.jpg",
  "image_name": "product_hero_image.jpg"
}

### Response
#### Success Response (200)
- **success** (boolean) - Operation status.
- **upload_details** (object) - Details of the uploaded image including image_hash.
```

--------------------------------

### create_ad_set_enhanced

Source: https://context7.com/brijr/meta-mcp/llms.txt

Creates a new ad set with advanced validation and configuration.

```APIDOC
## create_ad_set_enhanced

### Description
Creates a new ad set with advanced validation, targeting, and optimization goals.

### Request Body
- **campaign_id** (string) - Required
- **name** (string) - Required
- **daily_budget** (number) - Required
- **optimization_goal** (string) - Required
- **billing_event** (string) - Required
- **status** (string) - Required
- **targeting** (object) - Required
- **promoted_object** (object) - Required

### Request Example
{
  "campaign_id": "23851234567890456",
  "name": "US Women 30-50 Entrepreneurs",
  "daily_budget": 2500,
  "optimization_goal": "LINK_CLICKS",
  "billing_event": "IMPRESSIONS",
  "status": "PAUSED",
  "targeting": { ... },
  "promoted_object": { "page_id": "123456789012345" }
}

### Response
#### Success Response (200)
- **success** (boolean)
- **ad_set_id** (string)
- **message** (string)
- **details** (object)

#### Response Example
{
  "success": true,
  "ad_set_id": "23851234567891234",
  "message": "Ad set \"US Women 30-50 Entrepreneurs\" created successfully",
  "details": { ... }
}
```

--------------------------------

### POST create_ad

Source: https://context7.com/brijr/meta-mcp/llms.txt

Creates a new ad within an ad set using an existing creative.

```APIDOC
## POST create_ad

### Description
Creates a new ad within an ad set using an existing creative.

### Request Body
- **adset_id** (string) - Required - Ad set ID
- **name** (string) - Required - Ad name
- **creative** (object) - Required - Creative object containing creative_id
- **status** (string) - Required - Ad status

### Response
#### Success Response (200)
- **success** (boolean) - Operation success status
- **ad_id** (string) - Created ad ID
- **message** (string) - Status message
```

--------------------------------

### Upload Image from URL

Source: https://context7.com/brijr/meta-mcp/llms.txt

Downloads an image from a URL and uploads it to Meta's servers, returning an image_hash. This is required for carousel ads and recommended for better performance. Requires account ID, image URL, and image name.

```typescript
// MCP Tool Call
{
  "tool": "upload_image_from_url",
  "arguments": {
    "account_id": "act_123456789",
    "image_url": "https://example.com/images/product.jpg",
    "image_name": "product_hero_image.jpg"
  }
}

// Response
{
  "success": true,
  "message": "Image uploaded successfully to Meta",
  "api_version": "v23.0",
  "upload_details": {
    "account_id": "act_123456789",
    "original_url": "https://example.com/images/product.jpg",
    "uploaded_name": "product_hero_image.jpg",
    "image_hash": "abc123def456...",
    "meta_url": "https://scontent.xx.fbcdn.net/"
  },
  "next_steps": [
    "Use the image_hash \"abc123def456...\" in create_ad_creative",
    "The image is now stored in your Meta ad account library"
  ]
}
```

--------------------------------

### POST list_ads

Source: https://context7.com/brijr/meta-mcp/llms.txt

Lists all ads for a given campaign, ad set, or account with details on creative, status, and performance.

```APIDOC
## POST list_ads

### Description
Lists all ads for a given campaign, ad set, or account with details on creative, status, and performance.

### Request Body
- **campaign_id** (string) - Optional - Campaign ID to filter by
- **status** (string) - Optional - Ad status filter
- **limit** (integer) - Optional - Result limit

### Response
#### Success Response (200)
- **ads** (array) - List of ad objects
- **total_count** (integer) - Total number of ads found
```

--------------------------------

### POST get_token_info

Source: https://context7.com/brijr/meta-mcp/llms.txt

Retrieves information about the current access token including validity, expiration, and permissions.

```APIDOC
## POST get_token_info

### Description
Retrieves information about the current access token including validity, expiration, and permissions.

### Response
#### Success Response (200)
- **token_info** (object) - Token validity and scope details
- **current_config** (object) - Configuration status
- **token_status** (object) - Status flags
- **recommendations** (array) - Recommendations for the token
```

--------------------------------

### Fix npm Permissions

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Commands to resolve npm permission issues on macOS/Linux.

```bash
# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Or install without sudo
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

--------------------------------

### Test Meta API Token

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Manual verification of the Meta access token using curl.

```bash
# Test your token manually
curl -G \
  -d "access_token=YOUR_ACCESS_TOKEN" \
  "https://graph.facebook.com/v23.0/me/adaccounts"
```

--------------------------------

### List Ad Sets

Source: https://context7.com/brijr/meta-mcp/llms.txt

Lists all ad sets for a given campaign or ad account with optional status filtering and pagination.

```typescript
// MCP Tool Call
{
  "tool": "list_ad_sets",
  "arguments": {
    "campaign_id": "23851234567890456",
    "status": "ACTIVE",
    "limit": 25
  }
}

// Response
{
  "ad_sets": [
    {
      "id": "23851234567890789",
      "name": "US Audience 25-45",
      "campaign_id": "23851234567890456",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "daily_budget": "2500",
      "billing_event": "IMPRESSIONS",
      "optimization_goal": "LINK_CLICKS"
    }
  ],
  "pagination": {
    "has_next_page": false
  },
  "total_count": 1
}
```

--------------------------------

### resume_campaign

Source: https://context7.com/brijr/meta-mcp/llms.txt

Reactivates a previously paused campaign to resume ad delivery.

```APIDOC
## resume_campaign

### Description
Reactivates a previously paused campaign to resume ad delivery.

### Request Body
- **campaign_id** (string) - Required - The ID of the campaign to resume.

### Request Example
{
  "campaign_id": "23851234567890456"
}

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **campaign_id** (string) - The ID of the resumed campaign
- **message** (string) - Confirmation message
- **new_status** (string) - The updated status of the campaign

#### Response Example
{
  "success": true,
  "campaign_id": "23851234567890456",
  "message": "Campaign 23851234567890456 resumed successfully",
  "new_status": "ACTIVE"
}
```

--------------------------------

### create_ad_creative

Source: https://context7.com/brijr/meta-mcp/llms.txt

Creates a new ad creative with images, videos, text, and call-to-action buttons.

```APIDOC
## create_ad_creative

### Description
Creates a new ad creative with images, videos, text, and call-to-action buttons. Supports both external URLs and uploaded image hashes for v23.0 API compliance.

### Request Body
- **account_id** (string) - Required - The ID of the ad account.
- **name** (string) - Required - Name of the creative.
- **page_id** (string) - Required - The Facebook Page ID.
- **headline** (string) - Required - Ad headline.
- **message** (string) - Required - Ad body text.
- **picture** (string) - Optional - Image URL.
- **call_to_action_type** (string) - Required - CTA button type.
- **link_url** (string) - Required - Destination URL.
- **description** (string) - Optional - Ad description.
- **enable_standard_enhancements** (boolean) - Optional - Enable standard enhancements.
- **enhancement_features** (object) - Optional - Specific enhancement settings.

### Request Example
{
  "account_id": "act_123456789",
  "name": "Summer Sale Creative v1",
  "page_id": "123456789012345",
  "headline": "50% Off Everything",
  "message": "Our biggest summer sale is here! Shop now and save big on all products.",
  "picture": "https://example.com/images/summer-sale.jpg",
  "call_to_action_type": "SHOP_NOW",
  "link_url": "https://example.com/summer-sale",
  "description": "Free shipping on orders over $50",
  "enable_standard_enhancements": true,
  "enhancement_features": {
    "enhance_cta": true,
    "text_improvements": true,
    "image_brightness_and_contrast": true
  }
}

### Response
#### Success Response (200)
- **success** (boolean) - Operation status.
- **creative_id** (string) - The ID of the created creative.
- **api_version** (string) - The API version used.
```

--------------------------------

### Create Feature Branch

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Create a new branch for developing a new feature using Git.

```bash
git checkout -b feature/new-feature
```

--------------------------------

### Debug Mode Configuration

Source: https://github.com/brijr/meta-mcp/blob/main/README.md

Configuration for enabling debug logging in the MCP server.

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_MCP_DEBUG": "1",
        "NODE_ENV": "development"
      }
    }
  }
}
```

--------------------------------

### list_ad_sets

Source: https://context7.com/brijr/meta-mcp/llms.txt

Lists all ad sets for a given campaign or ad account with optional status filtering and pagination.

```APIDOC
## list_ad_sets

### Description
Lists all ad sets for a given campaign or ad account with optional status filtering and pagination.

### Request Body
- **campaign_id** (string) - Required - The ID of the campaign.
- **status** (string) - Optional - Filter by ad set status.
- **limit** (number) - Optional - Pagination limit.

### Request Example
{
  "campaign_id": "23851234567890456",
  "status": "ACTIVE",
  "limit": 25
}

### Response
#### Success Response (200)
- **ad_sets** (array) - List of ad set objects
- **pagination** (object) - Pagination metadata
- **total_count** (number) - Total number of ad sets found

#### Response Example
{
  "ad_sets": [
    {
      "id": "23851234567890789",
      "name": "US Audience 25-45",
      "campaign_id": "23851234567890456",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "daily_budget": "2500",
      "billing_event": "IMPRESSIONS",
      "optimization_goal": "LINK_CLICKS"
    }
  ],
  "pagination": {
    "has_next_page": false
  },
  "total_count": 1
}
```

--------------------------------

### Create Ad

Source: https://context7.com/brijr/meta-mcp/llms.txt

Create a new ad within an ad set using an existing creative. The ad can be created in a paused state.

```typescript
// MCP Tool Call
{
  "tool": "create_ad",
  "arguments": {
    "adset_id": "23851234567891234",
    "name": "Summer Sale Ad - Variation B",
    "creative": {"creative_id": "23851234567896789"},
    "status": "PAUSED"
  }
}

// Response
{
  "success": true,
  "ad_id": "23851234567898901",
  "message": "Ad \"Summer Sale Ad - Variation B\" created successfully"
}
```

--------------------------------

### Create Ad Creative

Source: https://context7.com/brijr/meta-mcp/llms.txt

Creates a new ad creative with images, videos, text, and call-to-action buttons. Supports external URLs and uploaded image hashes for v23.0 API compliance. Requires account ID, page ID, and creative content details.

```typescript
// MCP Tool Call
{
  "tool": "create_ad_creative",
  "arguments": {
    "account_id": "act_123456789",
    "name": "Summer Sale Creative v1",
    "page_id": "123456789012345",
    "headline": "50% Off Everything",
    "message": "Our biggest summer sale is here! Shop now and save big on all products.",
    "picture": "https://example.com/images/summer-sale.jpg",
    "call_to_action_type": "SHOP_NOW",
    "link_url": "https://example.com/summer-sale",
    "description": "Free shipping on orders over $50",
    "enable_standard_enhancements": true,
    "enhancement_features": {
      "enhance_cta": true,
      "text_improvements": true,
      "image_brightness_and_contrast": true
    }
  }
}

// Response
{
  "success": true,
  "creative_id": "23851234567896789",
  "message": "Ad creative \"Summer Sale Creative v1\" created successfully with v23.0 features",
  "api_version": "v23.0",
  "details": {
    "id": "23851234567896789",
    "name": "Summer Sale Creative v1",
    "page_id": "123456789012345",
    "headline": "50% Off Everything",
    "call_to_action_type": "SHOP_NOW"
  },
  "next_steps": [
    "Use this creative in ad creation",
    "Preview the creative across different placements",
    "Monitor enhancement performance in Meta Ads Manager"
  ]
}
```

--------------------------------

### Resume Campaign

Source: https://context7.com/brijr/meta-mcp/llms.txt

Reactivates a previously paused campaign to resume ad delivery.

```typescript
// MCP Tool Call
{
  "tool": "resume_campaign",
  "arguments": {
    "campaign_id": "23851234567890456"
  }
}

// Response
{
  "success": true,
  "campaign_id": "23851234567890456",
  "message": "Campaign 23851234567890456 resumed successfully",
  "new_status": "ACTIVE"
}
```

--------------------------------

### List Campaigns MCP Tool Call and Response

Source: https://context7.com/brijr/meta-mcp/llms.txt

Retrieve a paginated list of campaigns for a specific ad account, with optional status filtering and a limit. The response includes campaign details and pagination info.

```typescript
// MCP Tool Call
{
  "tool": "list_campaigns",
  "arguments": {
    "account_id": "act_123456789",
    "status": "ACTIVE",
    "limit": 25
  }
}
```

```typescript
// Response
{
  "campaigns": [
    {
      "id": "23851234567890123",
      "name": "Holiday Sale 2024",
      "objective": "OUTCOME_TRAFFIC",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "created_time": "2024-01-15T10:30:00+0000",
      "daily_budget": "5000",
      "budget_remaining": "3500"
    }
  ],
  "pagination": {
    "has_next_page": false,
    "next_cursor": null
  },
  "total_count": 1
}
```

--------------------------------

### Create Custom Audience

Source: https://context7.com/brijr/meta-mcp/llms.txt

Creates a custom audience from various sources including website visitors, customer lists, or app users.

```typescript
// MCP Tool Call
{
  "tool": "create_custom_audience",
  "arguments": {
    "account_id": "act_123456789",
    "name": "High Value Customers",
    "description": "Customers with LTV > $500",
    "subtype": "CUSTOM",
    "customer_file_source": "USER_PROVIDED_ONLY",
    "retention_days": 180
  }
}

// Response
{
  "success": true,
  "audience_id": "23851234567893456",
  "message": "Custom audience \"High Value Customers\" created successfully",
  "details": {
    "id": "23851234567893456",
    "name": "High Value Customers",
    "subtype": "CUSTOM",
    "retention_days": 180
  },
  "next_steps": [
    "Upload customer data to populate the audience",
    "Wait for the audience to process (may take a few hours)",
    "Use the audience in ad targeting once it's ready"
  ]
}
```

--------------------------------

### Update Campaign MCP Tool Call and Response

Source: https://context7.com/brijr/meta-mcp/llms.txt

Update an existing campaign's settings like name, budget, or status. The response indicates success and lists the applied updates.

```typescript
// MCP Tool Call
{
  "tool": "update_campaign",
  "arguments": {
    "campaign_id": "23851234567890456",
    "name": "Summer Sale 2024 - Updated",
    "daily_budget": 7500,
    "status": "ACTIVE"
  }
}
```

```typescript
// Response
{
  "success": true,
  "campaign_id": "23851234567890456",
  "message": "Campaign 23851234567890456 updated successfully",
  "updates_applied": {
    "name": "Summer Sale 2024 - Updated",
    "daily_budget": 7500,
    "status": "ACTIVE"
  }
}
```

--------------------------------

### Compare Performance Metrics

Source: https://context7.com/brijr/meta-mcp/llms.txt

Performs side-by-side performance comparison of multiple campaigns, ad sets, or ads with ranking by specified metrics.

```typescript
// MCP Tool Call
{
  "tool": "compare_performance",
  "arguments": {
    "object_ids": ["23851234567890456", "23851234567890789", "23851234567891012"],
    "level": "campaign",
    "date_preset": "last_7d",
    "metrics": ["impressions", "clicks", "spend", "ctr", "cpc"]
  }
}

// Response
{
  "comparison_results": [
    {
      "object_id": "23851234567890456",
      "object_name": "Summer Sale 2024",
      "object_type": "campaign",
      "metrics": {
        "total_impressions": 45000,
        "total_clicks": 1350,
        "total_spend": 162.00,
        "average_ctr": 3.00,
        "average_cpc": 0.12
      }
    },
    {
      "object_id": "23851234567890789",
      "object_name": "Fall Collection",
      "object_type": "campaign",
      "metrics": {
        "total_impressions": 38000,
        "total_clicks": 950,
        "total_spend": 133.00,
        "average_ctr": 2.50,
        "average_cpc": 0.14
      }
    }
  ],
  "rankings": {
    "ctr": [
      {"rank": 1, "object_name": "Summer Sale 2024", "value": 3.00},
      {"rank": 2, "object_name": "Fall Collection", "value": 2.50}
    ]
  }
}
```

--------------------------------

### Estimate Audience Size

Source: https://context7.com/brijr/meta-mcp/llms.txt

Use this tool to estimate the potential reach of your targeting configuration before creating an ad set. It requires account ID, targeting parameters, and optimization goal.

```typescript
// MCP Tool Call
{
  "tool": "estimate_audience_size",
  "arguments": {
    "account_id": "act_123456789",
    "targeting": {
      "age_min": 25,
      "age_max": 45,
      "genders": [1, 2],
      "geo_locations": {
        "countries": ["US"]
      },
      "interests": [
        {"id": "6003139266461", "name": "Entrepreneurship"}
      ]
    },
    "optimization_goal": "LINK_CLICKS"
  }
}

// Response
{
  "estimate": {
    "monthly_active_users": 12500000,
    "daily_active_users": 8500000,
    "formatted": {
      "monthly_active_users": "12.5M",
      "daily_active_users": "8.5M"
    }
  },
  "targeting_parameters": {
    "age_min": 25,
    "age_max": 45,
    "geo_locations": {"countries": ["US"]}
  },
  "recommendations": [
    "Good audience size for most campaign objectives.",
    "You have room to test different creative approaches.",
    "Consider creating exclusion audiences to avoid overlap."
  ]
}
```