Facebook Ads MCP Server

🇨🇿 Česká verze

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

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