Custom Facebook Ads MCP Server

Eigen MCP server (Python) voor Meta/Facebook Business Manager, met:

• data inladen via Marketing API (insights/reporting),

• campagnes opbouwen (campaigns, ad sets, ads, creatives),

• optimalisatie en budgetadvies op basis van best practices.

Architectuur en endpoints

• MCP-transport: stdio. Cursor (of een andere MCP-client) start het proces; er is geen apart HTTP-endpoint voor de MCP zelf.

• Meta API: alle calls gaan via de Graph API / Marketing API zoals de SDK (facebook-business) die gebruikt. Basis-URL:

  https://graph.facebook.com/{META_API_VERSION}/...

  De standaard API-versie in deze codebase is v25.0 (zet META_API_VERSION in .env gelijk aan wat je app ondersteunt).

Related MCP server: Meta Marketing API MCP Server

1) Vereisten

• Python 3.11+

• uv

• Een Meta Developer-app met Marketing API en een geldig access token met rechten op het gewenste ad account

Benodigde permissies (scopes) op het token:

• ads_management

• ads_read

• business_management

• pages_read_engagement

Zonder deze scopes kunnen tools deels of volledig falen.

2) Meta Developer-app aanmaken

1. Ga naar Meta for Developers.

2. Maak een app (kies het type dat past bij Marketing API / zakelijke ads).

3. Voeg het product Marketing API toe en voltooi de stappen die Meta vraagt.

4. Noteer onder App settings → Basic:

   • App ID → META_APP_ID

   • App Secret → META_APP_SECRET

3) Ad account en token (aanbevolen: System User)

Aanbevolen voor een stabiele, team- of server-achtige setup: een System user in Meta Business Settings (Gebruikers → System users), met toegewezen assets (het juiste ad account en indien nodig Pages). Genereer daar een token met de scopes hierboven.

• Ad account-ID in .env als act_<numeriek_id>. De server voegt act_ automatisch toe als je alleen het nummer invult.

Alternatieven (minder ideaal voor productie):

• Korte tokens uit de Graph API Explorer (vooral geschikt om even te testen).

• OAuth-flow (zie hieronder) om user tokens of long-lived tokens te verkrijgen.

4) OAuth- en token-endpoints (Meta)

Vervang {VERSION} door dezelfde waarde als META_API_VERSION (bijv. v25.0). Vervang placeholders door je echte app- en redirect-gegevens.

Redirect URI: in de Meta-app (bijv. onder Facebook Login / OAuth-instellingen) moet de OAuth redirect URI exact overeenkomen met {REDIRECT_URI} in bovenstaande requests.

5) Installatie en .env

git clone <jouw-repo-url> mcp-facebook-ads
cd mcp-facebook-ads
uv sync
cp .env.example .env   # of maak .env handmatig

Vul .env (zie .env.example voor veldnamen):

META_APP_ID=...
META_APP_SECRET=...
META_ACCESS_TOKEN=...
META_AD_ACCOUNT_ID=act_...
META_API_VERSION=v25.0

De server laadt .env via python-dotenv vanaf de working directory van het proces. Zorg dat de MCP in Cursor cwd op de projectroot heeft staan als je geen inline env in de MCP-config gebruikt.

Commit .env nooit; die staat in .gitignore.

6) Cursor-configuratie

Je kunt de MCP op twee manieren configureren:

1. Project (aanbevolen voor dit repo): .cursor/mcp.json in de projectroot (staat mogelijk niet in git; maak hem lokaal aan).

2. Globaal: Cursor Settings → MCP, afhankelijk van je Cursor-versie.

Voorbeeld .cursor/mcp.json (geldige JSON — geen //-comments). Vervang het pad door je eigen projectmap; secrets horen in .env in die map, niet in git.

Optie A — cwd op de projectroot (aanbevolen; .env wordt dan automatisch geladen):

{
  "mcpServers": {
    "facebook-ads": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_facebook_ads.server"],
      "cwd": "/ABSOLUUT/PAD/NAAR/mcp-facebook-ads"
    }
  }
}

Optie B — zonder cwd, met expliciet pad in uv run:

{
  "mcpServers": {
    "facebook-ads": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABSOLUUT/PAD/NAAR/mcp-facebook-ads",
        "python",
        "-m",
        "mcp_facebook_ads.server"
      ]
    }
  }
}

Secrets kun je óf in .env in die cwd laten staan, óf (minder ideaal) als env-object in mcp.json zetten — let op dat je die file dan niet deelt.

7) Delen met collega’s

Wel delen: repository, deze README, App ID, bekende ad account-identifiers waar ze toch al toegang toe moeten hebben, en het Cursor-commando + cwd.

Niet delen (alleen via een secrets manager of 1:1 veilig kanaal): META_APP_SECRET, META_ACCESS_TOKEN. Liever per persoon of per omgeving een eigen System user-token met minimale benodigde rechten dan één gedeelde token zonder rotatie.

8) Sneltest tegen de Graph API

Controleer of je token werkt (zelfde {VERSION} als in .env):

GET https://graph.facebook.com/{VERSION}/me?access_token={META_ACCESS_TOKEN}

Als dit faalt, los eerst app- en tokenconfiguratie op voordat je de MCP gebruikt.

9) Starten als MCP-server (handmatig)

uv run python -m mcp_facebook_ads.server

Draait op stdio; normaal start Cursor dit proces zelf.

10) Beschikbare toolgroepen

Account Management

• get_ad_accounts

• get_account_info

• get_account_pages

Campaigns

• get_campaigns

• get_campaign_details

• create_campaign

• update_campaign

• delete_campaign

Ad Sets

• get_adsets

• get_adset_details

• create_adset

• update_adset

• delete_adset

Ads

• get_ads

• get_ad_details

• create_ad

• update_ad

• delete_ad

Creatives & Media

• get_ad_creatives

• upload_ad_image

• create_ad_creative

• create_asset_feed_ad_creative

• update_ad_creative

• get_ad_previews

Insights & Reporting

• get_insights

• get_account_insights

• compare_performance

Audience & Targeting

• search_interests

• search_behaviors

• search_demographics

• search_geo_locations

• estimate_audience_size

Best Practices & Optimization

• get_campaign_templates

• create_campaign_from_template

• analyze_campaign

• suggest_budget_allocation

11) Best-practice defaults

• Nieuwe entities worden standaard met status PAUSED aangemaakt.

• Templates zijn beschikbaar voor awareness, traffic, leads, sales.

• Adviezen sturen op CTR/CPC, en op funnel-gescheiden structuur.

12) Veiligheid en governance

• Gebruik bij voorkeur een system user-token, niet je persoonlijke user-token.

• Geef productie-activatie (ACTIVE) pas na review.

• Log API-fouten en fbtrace_id-waarden voor snelle debugging bij Meta.

13) Testen

uv run pytest