facebook-ads-readonly
Read Facebook ad accounts, campaigns, ad sets, ads, creatives, and detailed Ads Insights through the Meta Marketing API.
Connect this API to an AI agent Browse all specs
What you can do with facebook-ads-readonly via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /me/adaccounts |
listFacebookAdAccounts | List ad accounts available to the connected Facebook user Method: GET Path: /me/adaccounts IMPORTANT: This function has 0 REQUIRED parameter(s) and 3 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Query Parameters: OPTIONAL: - fields: No description - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. |
| GET | /act_{adAccountId} |
getFacebookAdAccount | Get detailed ad account information Method: GET Path: /act_{adAccountId} IMPORTANT: This function has 1 REQUIRED parameter(s) and 1 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - adAccountId: Numeric Facebook ad account ID without the act_ prefix. Use account_id returned by listFacebookAdAccounts. Query Parameters: OPTIONAL: - fields: No description |
| GET | /act_{adAccountId}/campaigns |
listFacebookAdCampaigns | List campaigns in an ad account Method: GET Path: /act_{adAccountId}/campaigns IMPORTANT: This function has 1 REQUIRED parameter(s) and 4 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - adAccountId: Numeric Facebook ad account ID without the act_ prefix. Use account_id returned by listFacebookAdAccounts. Query Parameters: OPTIONAL: - fields: No description - effective_status: JSON-encoded array of delivery statuses. Example: ["ACTIVE","PAUSED","CAMPAIGN_PAUSED","ADSET_PAUSED"]. - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. |
| GET | /act_{adAccountId}/adsets |
listFacebookAdSets | List ad sets with budget, optimization, schedule, and targeting Method: GET Path: /act_{adAccountId}/adsets IMPORTANT: This function has 1 REQUIRED parameter(s) and 4 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - adAccountId: Numeric Facebook ad account ID without the act_ prefix. Use account_id returned by listFacebookAdAccounts. Query Parameters: OPTIONAL: - fields: No description - effective_status: JSON-encoded array of delivery statuses. Example: ["ACTIVE","PAUSED","CAMPAIGN_PAUSED","ADSET_PAUSED"]. - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. |
| GET | /act_{adAccountId}/ads |
listFacebookAds | List ads with creative and tracking details Method: GET Path: /act_{adAccountId}/ads IMPORTANT: This function has 1 REQUIRED parameter(s) and 4 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - adAccountId: Numeric Facebook ad account ID without the act_ prefix. Use account_id returned by listFacebookAdAccounts. Query Parameters: OPTIONAL: - fields: No description - effective_status: JSON-encoded array of delivery statuses. Example: ["ACTIVE","PAUSED","CAMPAIGN_PAUSED","ADSET_PAUSED"]. - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. |
| GET | /{adId} |
getFacebookAd | Get one ad with detailed creative and tracking configuration Method: GET Path: /{adId} IMPORTANT: This function has 1 REQUIRED parameter(s) and 1 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - adId: Numeric Facebook ad ID. Query Parameters: OPTIONAL: - fields: No description |
| GET | /act_{adAccountId}/adcreatives |
listFacebookAdCreatives | List detailed creative assets in an ad account Method: GET Path: /act_{adAccountId}/adcreatives IMPORTANT: This function has 1 REQUIRED parameter(s) and 3 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - adAccountId: Numeric Facebook ad account ID without the act_ prefix. Use account_id returned by listFacebookAdAccounts. Query Parameters: OPTIONAL: - fields: No description - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. |
| GET | /act_{adAccountId}/insights |
getFacebookAdAccountInsights | Get detailed Ads Insights for an ad account Method: GET Path: /act_{adAccountId}/insights IMPORTANT: This function has 1 REQUIRED parameter(s) and 11 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - adAccountId: Numeric Facebook ad account ID without the act_ prefix. Use account_id returned by listFacebookAdAccounts. Query Parameters: OPTIONAL: - fields: Comma-separated reporting dimensions and metrics. The default includes delivery, cost, click, conversion, video, engagement, and ROAS fields. - level: No description - date_preset: Preset reporting period. Omit this when time_range is supplied. - time_range: JSON-encoded custom date range with since and until in YYYY-MM-DD. Omit date_preset when using this parameter. - time_increment: Use 1 for daily rows, monthly for calendar months, or all_days for one aggregate row covering the whole range. - breakdowns: Comma-separated breakdowns such as age,gender,country,region, publisher_platform,platform_position,device_platform,impression_device. Meta restricts which breakdown combinations are valid. - action_breakdowns: Comma-separated action breakdowns such as action_type, action_destination, action_device, and action_reaction. - filtering: JSON-encoded array of filters. Example: [{"field":"ad.effective_status","operator":"IN","value":["ACTIVE"]}]. - action_attribution_windows: JSON-encoded attribution windows such as ["1d_view","7d_click"]. - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. |
| GET | /{objectId}/insights |
getFacebookAdObjectInsights | Get Insights for one campaign, ad set, or ad Method: GET Path: /{objectId}/insights IMPORTANT: This function has 1 REQUIRED parameter(s) and 10 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - objectId: Numeric campaign ID, ad set ID, or ad ID. Query Parameters: OPTIONAL: - fields: Comma-separated reporting dimensions and metrics. The default includes delivery, cost, click, conversion, video, engagement, and ROAS fields. - date_preset: Preset reporting period. Omit this when time_range is supplied. - time_range: JSON-encoded custom date range with since and until in YYYY-MM-DD. Omit date_preset when using this parameter. - time_increment: Use 1 for daily rows, monthly for calendar months, or all_days for one aggregate row covering the whole range. - breakdowns: Comma-separated breakdowns such as age,gender,country,region, publisher_platform,platform_position,device_platform,impression_device. Meta restricts which breakdown combinations are valid. - action_breakdowns: Comma-separated action breakdowns such as action_type, action_destination, action_device, and action_reaction. - filtering: JSON-encoded array of filters. Example: [{"field":"ad.effective_status","operator":"IN","value":["ACTIVE"]}]. - action_attribution_windows: JSON-encoded attribution windows such as ["1d_view","7d_click"]. - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. |
Usage guide
Connect a Facebook account through OAuth2 with the ads_read permission. This template is read-only and contains GET operations only. It cannot create, update, delete, publish, pause, or spend advertising money.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “facebook-ads-readonly” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.