meta-ads-mcp-python 1.0.80

MCP server for Meta Ads API -- manage campaigns, ad sets, ads, and Business Manager accounts

Meta Ads MCP

A Model Context Protocol (MCP) server for analysing Meta Ads campaigns through an AI interface. Retrieve performance data, visualize ad creatives, and surface insights for Facebook, Instagram, and other Meta platforms.

Read-only: All tools are strictly read-only. No tool creates, modifies, or deletes any data.

Independent project: This is an open-source project using Meta's public APIs. Not affiliated with or endorsed by Meta. For an officially approved Meta app, see Pipeboard.

---

Quick Start (Remote MCP)

The fastest way to get started is the Pipeboard remote MCP — no local setup required.

Remote MCP URL: https://mcp.pipeboard.co/meta-ads-mcp

With token auth: https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN

Get your token at pipeboard.co/api-tokens.

Claude (Pro/Max)

1. Go to claude.ai/settings/integrations
2. Click Add Integration, set the URL to https://mcp.pipeboard.co/meta-ads-mcp
3. Click Connect and follow the prompts.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN"
    }
  }
}

Other MCP Clients

Use the remote URL above. Full setup guides: pipeboard.co

---

Local Installation

For advanced users. The remote MCP is recommended for most cases.

Requirements: Python 3.12+, a Meta Developer App (App ID + Secret), and uv.

pip install meta-ads-mcp

Authentication

Copy .env.example to .env and set one of:

PIPEBOARD_API_TOKEN=your_token       # Recommended — no Meta app required
META_APP_ID=your_app_id              # Direct Meta app credentials
META_APP_SECRET=your_app_secret

Run

meta-ads-mcp                         # stdio (default)
python -m meta_ads_mcp --transport streamable-http --host localhost --port 8080  # HTTP

Claude Desktop config

{
  "mcpServers": {
    "meta-ads": {
      "command": "meta-ads-mcp"
    }
  }
}

---

Configuration

Variable	Description
PIPEBOARD_API_TOKEN	Pipeboard API token (recommended)
META_APP_ID	Meta Developer App ID (direct auth)
META_APP_SECRET	Meta Developer App Secret (direct auth)
LOG_LEVEL	DEBUG, INFO, WARNING, ERROR (default: INFO)
SERVER_HOST	HTTP transport host (default: localhost)
SERVER_PORT	HTTP transport port (default: 8080)

---

Available Tools

Tool	Description
mcp_meta_ads_get_ad_accounts	List accessible ad accounts
mcp_meta_ads_get_account_info	Get details for a specific ad account
mcp_meta_ads_get_account_pages	Get pages associated with an ad account
mcp_meta_ads_get_campaigns	List campaigns with optional status filter
mcp_meta_ads_get_campaign_details	Get details for a specific campaign
mcp_meta_ads_get_adsets	List ad sets, optionally filtered by campaign
mcp_meta_ads_get_adset_details	Get details for a specific ad set
mcp_meta_ads_get_ads	List ads, optionally filtered by campaign or ad set
mcp_meta_ads_get_ad_details	Get details for a specific ad
mcp_meta_ads_get_ad_creatives	Get creative details (text, images, URLs)
mcp_meta_ads_get_ad_image	Download and visualize an ad image
mcp_meta_ads_get_insights	Get performance metrics with attribution windows and breakdowns
mcp_meta_ads_get_login_link	Get a login link for Meta authentication
mcp_meta_ads_search_interests	Search interest targeting options by keyword
mcp_meta_ads_get_interest_suggestions	Get interest suggestions based on existing interests
mcp_meta_ads_validate_interests	Validate interest names or IDs
mcp_meta_ads_search_behaviors	List available behavior targeting options
mcp_meta_ads_search_demographics	List demographic targeting options
mcp_meta_ads_search_geo_locations	Search geographic targeting locations
mcp_meta_ads_search	Generic search across accounts, campaigns, ads, and pages
mcp_meta_ads_get_businesses	List all Business Manager accounts
mcp_meta_ads_get_business_ad_accounts	List ad accounts under a Business Manager
mcp_meta_ads_find_client_account	Search for a client account across Business Managers
mcp_meta_ads_get_business_details	Get details for a specific Business Manager

---

Troubleshooting

• Auth errors: Check your token/credentials in .env. Use mcp_meta_ads_get_login_link to re-authenticate.
• No accounts returned: Ensure the user has access to at least one ad account in Meta Business Manager.
• Tool not found: Confirm the server is running and your client config is correct.

---

Privacy and Security

• Remote MCP: auth is handled in the cloud, no tokens stored locally.
• Local install: tokens are cached on your machine. Never commit your .env file.
• The server never exposes your access token to the LLM.

---

Licensing

Licensed under the Business Source License 1.1. Free for individual and business use. Converts to Apache 2.0 on January 1, 2029. You may not offer this as a competing hosted service.

For commercial licensing: [e-mail]

---

Support

• Discord
• GitHub Issues
• Email