Meta Ads MCP Server

A Model Context Protocol server for the Meta (Facebook) Ads API, written in TypeScript.
Provides 24 tools to manage and analyze ad accounts, campaigns, ad sets, ads, creatives, insights, and activity logs via the Meta Graph API v22.0.

Works with Cursor, Claude Desktop (stdio) and Claude.ai custom connectors (HTTP).

Disclaimer: This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs in accordance with their Terms of Service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.

---

Table of Contents

• Features
• Requirements
• Installation
• Authentication
• Transport Modes
• Cursor / Claude Desktop Setup
• Remote HTTP Server
• Available Tools
• Pagination
• Development
• Project Structure
• Disclaimer
• License

---

Features

Category	Description
Accounts	List ad accounts, get account details
Insights	Performance analytics at account, campaign, ad set, and ad level
Campaigns	Get by ID, list by ad account with filtering and pagination
Ad Sets	Get by ID, batch lookup, list by ad account or campaign
Ads	Get by ID, list by ad account, campaign, or ad set
Creatives	Get creative details, list by ad or by ad account
Media	List ad images, generate ad previews across placements
Activities	Change history log for ad accounts and ad sets
Pagination	Utility tool to fetch subsequent pages of results

---

Requirements

• Node.js >= 18
• A Meta User Access Token with at minimum the ads_read permission — generate one from the Meta Graph API Explorer

---

Installation

# Install dependencies
npm install

# Build TypeScript
npm run build

Or run directly without installing via npx:

npx meta-ads-mcp-server --access-token YOUR_META_ACCESS_TOKEN

---

Authentication

Pass your Meta access token using either method:

CLI argument (recommended for Cursor / Claude Desktop):

node dist/index.js --access-token YOUR_META_ACCESS_TOKEN

Environment variable:

export META_ADS_ACCESS_TOKEN=YOUR_META_ACCESS_TOKEN
node dist/index.js

---

Transport Modes

Mode	Use case	How to enable
stdio (default)	Cursor, Claude Desktop, local tools	No configuration needed
http	Claude.ai remote connectors, multi-client setups	Set TRANSPORT=http

---

Cursor / Claude Desktop Setup

Add one of the following to your MCP client configuration file:

Via npx (recommended — no local install required):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp-server", "--access-token", "YOUR_META_ACCESS_TOKEN"]
    }
  }
}

Via local build:

{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["/path/to/meta-ads-mcp/dist/index.js", "--access-token", "YOUR_META_ACCESS_TOKEN"]
    }
  }
}

Via environment variable:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp-server"],
      "env": {
        "META_ADS_ACCESS_TOKEN": "YOUR_META_ACCESS_TOKEN"
      }
    }
  }
}

---

Remote HTTP Server

Run as a persistent HTTP server for use with Claude.ai custom connectors or any remote MCP client.

# Start on default port 3000
TRANSPORT=http META_ADS_ACCESS_TOKEN=YOUR_TOKEN node dist/index.js

# Start on a custom port
TRANSPORT=http META_ADS_ACCESS_TOKEN=YOUR_TOKEN PORT=8080 node dist/index.js

Endpoints:

• POST /mcp — MCP protocol endpoint
• GET /health — Health check ({"status":"ok"})

Adding to Claude.ai

1. Go to Settings → Connectors → Add custom connector
2. Enter your server URL: https://your-domain.com/mcp
3. Click Add

Local testing with ngrok

# Terminal 1 — start the server
TRANSPORT=http META_ADS_ACCESS_TOKEN=YOUR_TOKEN PORT=8080 node dist/index.js

# Terminal 2 — expose publicly
ngrok http 8080

Use the generated HTTPS URL (e.g. https://xxxx.ngrok-free.app/mcp) as your connector URL.

Deploying to cloud platforms

Set the following environment variables on your hosting provider (Railway, Render, Fly.io, etc.):

Variable	Value
TRANSPORT	http
META_ADS_ACCESS_TOKEN	Your Meta access token
PORT	Assigned automatically by the platform

---

Available Tools

View all 24 tools

Tool	Description
meta_ads_list_ad_accounts	List all ad accounts accessible with your token
meta_ads_get_ad_account_details	Get detailed information for a specific ad account
meta_ads_get_adaccount_insights	Retrieve performance insights for an ad account
meta_ads_get_campaign_insights	Retrieve performance insights for a campaign
meta_ads_get_adset_insights	Retrieve performance insights for an ad set
meta_ads_get_ad_insights	Retrieve performance insights for an individual ad
meta_ads_get_campaign_by_id	Fetch a specific campaign by its ID
meta_ads_get_campaigns_by_adaccount	List all campaigns within an ad account
meta_ads_get_adset_by_id	Fetch a specific ad set by its ID
meta_ads_get_adsets_by_ids	Batch fetch multiple ad sets by their IDs
meta_ads_get_adsets_by_adaccount	List all ad sets within an ad account
meta_ads_get_adsets_by_campaign	List all ad sets within a campaign
meta_ads_get_ad_by_id	Fetch a specific ad by its ID
meta_ads_get_ads_by_adaccount	List all ads within an ad account
meta_ads_get_ads_by_campaign	List all ads within a campaign
meta_ads_get_ads_by_adset	List all ads within an ad set
meta_ads_get_ad_creative_by_id	Fetch a specific ad creative by its ID
meta_ads_get_ad_creatives_by_ad_id	List all creatives associated with an ad
meta_ads_get_adcreatives_by_adaccount	List all creatives within an ad account
meta_ads_get_ad_images	List image assets in an ad account
meta_ads_get_ad_previews	Generate rendered previews of an ad across placements
meta_ads_get_activities_by_adaccount	Retrieve the change history log for an ad account
meta_ads_get_activities_by_adset	Retrieve the change history log for an ad set
meta_ads_fetch_pagination_url	Fetch the next or previous page of a paginated result

---

Pagination

Many list tools return paginated results. When a response contains a paging.next URL, use meta_ads_fetch_pagination_url to retrieve subsequent pages:

1. Call meta_ads_get_campaigns_by_adaccount  →  receive first page
2. Check if response.paging.next exists
3. Call meta_ads_fetch_pagination_url(url=response.paging.next)  →  receive next page
4. Repeat until paging.next is absent

---

Development

npm run dev              # Watch mode — auto-recompile on change
npm run build            # Compile TypeScript to dist/
npm run clean            # Remove dist/
npm run clean && npm run build   # Full rebuild from scratch

---

Project Structure

meta-ads-mcp/
├── src/
│   ├── index.ts              # Entry point, server setup, transport selection
│   ├── constants.ts          # API version, base URLs, default values
│   ├── types.ts              # Shared TypeScript interfaces
│   ├── services/
│   │   └── graph-api.ts      # HTTP client, auth, error handling, param builders
│   ├── schemas/
│   │   ├── common.ts         # Shared Zod schemas (pagination, date ranges, filters)
│   │   └── insights.ts       # Insights-specific Zod schemas
│   └── tools/
│       ├── accounts.ts       # Account tools
│       ├── insights.ts       # Insights tools
│       ├── campaigns.ts      # Campaign tools
│       ├── adsets.ts         # Ad set tools
│       ├── ads.ts            # Ad tools
│       ├── creatives.ts      # Creative tools
│       ├── media.ts          # Image and preview tools
│       ├── activities.ts     # Activity log tools
│       └── pagination.ts     # Pagination utility tool
├── dist/                     # Compiled JavaScript output (generated)
├── package.json
└── tsconfig.json

---

License

MIT © hashcott