Meta Ads MCP Server

How to use

You interact with the MCP server from your MCP client (for example Claude Desktop or Cursor) by configuring a server entry that points to either a local stdio process or a remote HTTP endpoint. The server exposes a set of tools to manage campaigns, pull analytics, handle audiences, and create or review ad creatives. Use the client to issue high-level actions like creating a campaign, retrieving insights, or building audiences, and rely on the server to translate those requests into Meta Marketing API calls with proper error handling and rate limiting.

Typical usage patterns include: creating a new campaign with a target objective, fetching performance data for a date range, listing ad accounts, or generating lookalike audiences. You can also set up health checks to verify authentication and connectivity before running production workloads.

How to install

Prerequisites: you need Node.js and npm installed on your system.

# Install the MCP server globally
npm install -g meta-ads-mcp

# Optional: verify version
meta-ads-mcp --version

Configuration and startup

Configure your MCP client to connect to the local MCP server or the remote endpoint. The source provides concrete configuration examples for Claude Desktop and Cursor. Use these as starting points and replace placeholders with your actual tokens and IDs.

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

Starting with Claude Desktop or Cursor

Add the MCP server configuration to your client’s settings. For Claude Desktop the configuration path is your client’s MCP configuration file. For Cursor, add the same JSON block in the Claude extension settings.

Verify setup

After configuring, restart your client and run a health check to confirm the server is reachable and authenticated.

npm run health-check

get_insights

Retrieve detailed performance metrics such as impressions, clicks, ROAS, CTR, CPC, and more for specified accounts and date ranges.

compare_performance

Compare performance across multiple campaigns or ads side-by-side within a given date range.

export_insights

Export performance data in JSON or CSV formats for reporting and analysis.

create_campaign

Create a new advertising campaign with full configuration including objective and budget.

update_campaign

Update properties of an existing campaign such as name, budget, or status.

pause_campaign

Pause active campaigns to halt spending.

resume_campaign

Resume paused campaigns to restart ads serving.

create_ad_set

Create ad sets with targeting, budget, schedule, and optimization goals.

list_ad_sets

List ad sets within campaigns with filtering options.

create_ad

Create a new ad within an ad set using a specified creative.

list_ads

List ads with filtering by ad set, campaign, or account.

list_audiences

List all custom audiences for an account.

create_custom_audience

Create a custom audience from various sources.

create_lookalike_audience

Generate a lookalike audience from a source audience.

get_audience_info

Get detailed information about a specific audience.

list_ad_creatives

List all ad creatives for an account.

create_ad_creative

Create new ad creatives with rich specifications (supports external image URLs).

health_check

Perform a comprehensive authentication and server status check.

get_ad_accounts

List accessible Meta ad accounts.

get_campaigns

List campaigns with filtering options.

get_token_info

Validate the current access token and show its permissions and expiry.

diagnose_campaign_readiness

Check if a campaign is ready for ad set creation and identify issues.

check_account_setup

Validate account setup including payment methods and permissions.