Every tool is a get or a list — no create, no update, no state change, no path to a budget — which makes this a reporting surface you can hand over without a review step in front of it. The reporting is split into four tools by scope rather than one tool with a scope argument, and each carries the same ranking controls, so the top ad in the account and the top ad within one ad group are the same query at different levels. The convention to get right before reading anything aloud is the unit: spend and bid figures come back in micros and have to be divided by 1,000,000.
A read-only OpenAI Ads reporting client of 11 tools: the account, the campaign, ad group and ad tree, and a dedicated insights endpoint for each of those four levels.
- get_ad_account, which doubles as a connectivity check and returns the account's name, currency, status and timezone; each API key is scoped to a single ad account.
- The tree read at every level: list_campaigns and get_campaign with objective, status, budget and country targeting; list_ad_groups and get_ad_group with the bidding configuration and context hints; list_ads and get_ad with the creative and a review_status of in_review, approved or rejected.
- Insights as four separate tools rather than one scoped call — get_account_insights, get_campaign_insights, get_ad_group_insights and get_ad_insights — each returning rows with id, start_time and end_time plus projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name and ad_name.
- Ranking built into the insights call: aggregation_level, sort and limit combine to return the top entities rather than everything, alongside filters, a time granularity and a since and until window.
- Cursor pagination throughout, with first_id, last_id and has_more on every list response.
OPENAI_ADS_API_KEY, scoped to the single ad account it belongs to — get_ad_account confirms which one. An awareness of the unit convention before any figure is shown to a person: monetary values arrive in micros, where 1,000,000 micros is one unit of the account's currency.
One command plus a key — npx -y @hypd-ai/openai-ads-mcp, then supply credentials