@bossforce.ai/mcp-meta-ads

BossForce MCP server for Meta Ads (Facebook and Instagram advertising) via the Meta Marketing API on the Graph API.

Read-only: discover ad accounts, list campaigns, and pull performance insights (impressions, clicks, spend) over a date range.

Tools

| Tool | Method | Graph edge | | ------------------ | ------ | -------------------------------- | | list_ad_accounts | GET | /me/adaccounts | | list_campaigns | GET | /act_{ad_account_id}/campaigns | | get_insights | GET | /act_{ad_account_id}/insights |

ad_account_id is a tool argument (accepted with or without the act_ prefix).

Auth

OAuth2 (oauth_service: facebook). The server uses a long-lived Meta user or system-user access token directly as an HTTP Bearer token against https://graph.facebook.com/{version} (default v22.0, override with META_ADS_GRAPH_VERSION).

| Env | Purpose | | ----------------------------------------------- | ---------------------------------------------------- | | META_ADS_CLIENT_ID / META_ADS_CLIENT_SECRET | App credentials (platform mcp_env). | | META_ADS_ACCESS_TOKEN | Long-lived user / system-user access token (Bearer). | | META_ADS_GRAPH_VERSION | Optional Graph API version, e.g. v22.0. |

The token is read lazily, cached, and re-read once on a 401.

Gating (production)

Using this in production requires:

• A Meta app with the Marketing API product.
• The ads_read / ads_management permissions, which must pass Meta App Review and Business Verification. Before review, these permissions only work for users who have an Admin/Developer/Tester role on the app.
• A long-lived (~60 day) user token or a System User token issued in Business Manager, granted access to the target ad accounts. Meta has no OAuth2 refresh_token grant for these tokens, so the token must be re-issued before it expires — there is no automated server-side refresh.

Error mapping

HTTP status and Graph error codes map onto the BossForce taxonomy: 190 / 401 / 403 / permission codes -> auth; 429 and codes 4/17/32/613 (and 80000-series subcodes) -> rate_limit; 404 -> not_found; 400 / 422 -> validation; everything else -> upstream.