READMEmain

Facebook Ads MCP Server

MCP server for managing Facebook ads straight from Claude AI. No manual token hunting — sign in with Facebook once and you're done.

Features

Campaign management (create, update, delete)
Ad sets and individual ads
Analytics and insights
Custom and lookalike audiences
Page posts
Automatic token management (page tokens are permanent)

Installation

Requirements

Node.js 18+
Claude Desktop

1. Clone the repository

git clone https://github.com/Tisik79/MCP-Facebook.git
cd MCP-Facebook
npm install
npm run build

2. Add to Claude Desktop

Open the Claude Desktop config file:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add:

{
  "mcpServers": {
    "facebook-ads": {
      "command": "node",
      "args": ["/PATH/TO/MCP-Facebook/dist/index.js"]
    }
  }
}

3. First run — 5-minute setup

On first start, a wizard walks you through creating your own Facebook App:

Steps:
  1. Click "Create App"
  2. Choose type: "Business"
  3. Enter any name (e.g. "My Ads")
  4. After creation, go to Settings → Basic
  5. Copy the App ID and App Secret
  6. Add the "Facebook Login" product and set:
     Valid OAuth Redirect URIs: http://localhost:3456/auth/callback
  7. In Basic settings, add "localhost" to App Domains

After entering the App ID and Secret, a browser opens automatically → sign in with Facebook → done.

Re-login / adding pages

node dist/index.js login

Usage in Claude

"Show my active campaigns"
"Create a campaign for MyBrand with a $20 daily budget"
"How did my ads perform last month?"
"Post an update to page XY"

Available Tools

Tool	Description
`connect_facebook_account` / `set_facebook_token`	Sign in via OAuth / store a token from Graph API Explorer
`list_connected_accounts` / `set_active_account`	Show connected pages & accounts / switch the active one
`facebook_setup_help`	Step-by-step connection guide
`get_campaigns`	List campaigns
`create_campaign`	Create a new campaign
`update_campaign`	Update a campaign (incl. `bidStrategy`) — read-after-write
`get_campaign_details`	Campaign detail (budget, bid_strategy, spend today)
`delete_campaign`	Delete a campaign
`get_campaign_insights`	Campaign analytics
`get_adset_insights` / `get_ad_insights`	Ad set / ad level analytics
`get_adsets`	List ad sets
`create_ad_set`	Create an ad set (incl. lead fields `promotedObject` / `destinationType`)
`update_adset`	Update an ad set (name / status) — real write + read-after-write verification
`get_ads`	List ads (filtered via adSetId/campaignId edge + status)
`get_ad`	Ad detail incl. creative (link, CTA, copy, video/image)
`upload_ad_media`	Upload an image (`image_hash`) or video (`video_id`)
`create_adcreative`	Create a creative from `object_story_spec`
`create_ad`	Create an ad (defaults to PAUSED)
`update_ad`	Update an ad (name/status/creative) — read-after-write
`delete_ad`	Delete an ad
`create_lead_form`	Create an instant lead form on a page
`get_lead_forms`	List lead forms (`id`, `name`, `status`, `leads_count`)
`get_pixels`	Account pixels (`id`, `name`) for `promoted_object`
`create_pixel` / `update_pixel` / `get_pixel`	Pixel management (detail incl. `last_fired_time`)
`get_pixel_stats`	Pixel event statistics (verify events are flowing)
`search_interests` / `get_interest_suggestions`	Interest search & suggestions for targeting
`search_behaviors`	Behavior categories for targeting
`search_geo_locations`	Geo keys (region/city/zip) for `targeting.geo_locations`
`estimate_audience_size`	Audience size estimate for a given targeting spec
`send_conversion_event` / `send_conversion_events_batch`	Conversions API — server-side events (auto SHA-256 PII hashing)
`get_custom_conversions` / `get_custom_conversion`	List / detail of custom conversions
`create_custom_conversion` / `update_custom_conversion` / `delete_custom_conversion`	Custom conversions (`custom_conversion_id` for lead campaigns)
`get_offline_conversion_sets` / `create_offline_conversion_set` / `upload_offline_conversions`	Offline conversions from your CRM
`update_adcreative`	Update a creative (name/status — content is immutable)
`get_audiences`	Custom audiences
`create_custom_audience`	Create an audience
`create_lookalike_audience`	Lookalike audience
`create_post`	Page post
`create_video_post`	Video page post (resumable upload, unpublished by default)

The scope of the targeting/conversion tool set was inspired by Draivix/aidvertaiser (David Strejc, MIT) — thanks!

Lead Campaigns (OUTCOME_LEADS)

Lead collection has two paths; both require promotedObject + destinationType on the ad set:

Website conversions — optimizationGoal=OFFSITE_CONVERSIONS, destinationType=WEBSITE, promotedObject={ pixel_id, custom_event_type: "LEAD" } (find your Pixel ID via get_pixels).
Instant form — optimizationGoal=LEAD_GENERATION, destinationType=ON_AD, promotedObject={ page_id }, creative with call_to_action.value.lead_gen_form_id (create the form via create_lead_form).

Without promotedObject + destinationType, Meta returns "Invalid parameter". For accounts with campaign-level budget (CBO), do not set a budget on the ad set — it inherits from the campaign. If the campaign uses a cap bid strategy (LOWEST_COST_WITH_BID_CAP), the ad set requires bidAmount; otherwise set the campaign to bidStrategy=LOWEST_COST_WITHOUT_CAP.

License

MIT

MCP-Facebook