Facebook Ads MCP Server

MCP server for Meta/Facebook Marketing API workflows.

It provides tools to:

• View ad accounts, campaigns, ad sets, ads, creatives, and activity history.

• Create and update campaigns, ad sets, ads, and creatives.

• Fetch insights at account/campaign/adset/ad level.

• Upload ad images (local file path only).

Requirements

• Python 3.10+

• A Meta user access token with required scopes

• Access to at least one ad account

Related MCP server: mcp-meta-marketing

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Authentication

The server supports either:

• CLI arg: --fb-token <TOKEN>

• Environment variable: FACEBOOK_ACCESS_TOKEN (or FB_ACCESS_TOKEN)

Recommended local setup (.env)

cp .env.example .env
# then set FACEBOOK_ACCESS_TOKEN in .env

The server automatically loads .env via python-dotenv.

Running Locally

python server.py --fb-token YOUR_META_ACCESS_TOKEN

or with .env configured:

python server.py

MCP Client Configuration

Example:

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "FACEBOOK_ACCESS_TOKEN": "YOUR_META_ACCESS_TOKEN"
      }
    }
  }
}

If your client does not support env, pass --fb-token in args.

Tool Coverage

Read/List

• list_ad_accounts

• get_details_of_ad_account

• get_campaigns_by_adaccount, get_campaign_by_id

• get_adsets_by_adaccount, get_adsets_by_campaign, get_adsets_by_ids, get_adset_by_id

• get_ads_by_adaccount, get_ads_by_campaign, get_ads_by_adset, get_ad_by_id

• get_ad_creatives_by_ad_id, get_ad_creative_by_id

• get_activities_by_adaccount, get_activities_by_adset

Create/Update

• create_campaign, update_campaign

• create_adset, update_adset

• create_ad, update_ad

• create_ad_creative, create_link_ad_creative

• upload_ad_image

Insights

• get_adaccount_insights

• get_campaign_insights

• get_adset_insights

• get_ad_insights

• fetch_pagination_url

Important: upload_ad_image Is Local Path Only

upload_ad_image intentionally accepts only:

• act_id

• image_path

• optional name

It does not accept image_url.

Reason: URL ingestion through /{ad_account_id}/adimages is inconsistent across app/account capability states and commonly fails even when local upload works. Restricting this tool to local paths avoids ambiguous behavior.

Example:

upload_ad_image(
    act_id="act_1234567890",
    image_path="/absolute/path/to/creative.png",
    name="creative_v1"
)

Permissions and Access Checklist

Need the full end-to-end setup for Meta Business Center + App Dashboard? See docs/meta-business-center-setup.md.

For most ad management/read workflows, ensure the token has:

• ads_management

• ads_read

• business_management

Page-related creative/ad flows may additionally need page scopes such as:

• pages_show_list

• pages_read_engagement

• pages_manage_ads

Operational requirements:

• The user tied to the token is added to the target ad account with sufficient role (typically Advertiser/Admin).

• The app is configured for Marketing API use case.

• In Development mode, only app roles/test users can use the app token flow.

• For non-role external users, required permissions/features must be approved for advanced access and app must be Live.

Common Failure Modes

• (#200) Permissions error:

  • Missing permission scope on token, or user lacks ad account role.

• Empty ad account list:

  • User/token has no accessible ad accounts.

• upload_ad_image file error:

  • image_path is missing, relative to wrong runtime location, or file does not exist.

Security Notes

• Never commit real tokens.

• .env is git-ignored; keep secrets there for local use.

• Rotate tokens if they were ever exposed.

Development

Run a quick syntax check:

python3 -m py_compile server.py

License

MIT