Hypd Ai Openai Ads

AModel Context Protocol (MCP)server for theOpenAI Ads (Advertiser) API. It lets MCP-compatible clients — Claude Desktop, Cursor, VS Code, and others — read your OpenAI Ads campaigns, ad groups, ads, and performance insights through natural language.

Read-only.This first release onlyreadsdata — it never creates, edits, or pauses anything and never spends budget. Write actions are on theroadmap.

Unofficial.This is a community project and isnot affiliated with or endorsed by OpenAI. See thedisclaimer.

TheOpenAI Ads APIexposes an advertiser's account, campaigns, ad groups, ads, and reporting. This server wraps the read endpoints of that API as MCP tools so an AI assistant can answer questions like:

- 11 read-only toolscovering the account, campaigns, ad groups, ads, and insights at every level.
- Faithful responses— the API's JSON is returned as-is, so nothing is lost in translation.
- Clear errors— HTTP status and the API error body are surfaced to the model instead of being swallowed.
- Micros-aware— every tool description explains themicros conventionso the assistant can present human-readable currency.
- Cursor paginationpassthrough (limit,order,after,before).
- Zero-installvianpx—npx -y @hypd-ai/openai-ads-mcp, no clone or build.

- Node.js 20 or newer.
- An OpenAI Ads API key.Create an Ads account atads.openai.com(currentlyUS-only), then issue a key fromSettings→ads.openai.com/settings. See thequickstartandauthenticationdocs. Each key isscoped to a single ad account.

Published on npmas@hypd-ai/openai-ads-mcp—npxfetches it for you, so there's nothing to clone or build. To run the latestunreleasedmaininstead, replace@hypd-ai/openai-ads-mcpwithgithub:HYPD-AI/openai-ads-mcp(its first launch builds from source — seeRunning from source).

{ "mcpServers": { "openai-ads": { "command": "npx", "args": ["-y", "@hypd-ai/openai-ads-mcp"], "env": { "OPENAI_ADS_API_KEY": "your-openai-ads-api-key" } } } }

Restart Claude Desktop, then ask:"Use the openai-ads tools to look up my ad account."

Add to~/.cursor/mcp.json(global) or.cursor/mcp.json(per-project):

{ "mcpServers": { "openai-ads": { "command": "npx", "args": ["-y", "@hypd-ai/openai-ads-mcp"], "env": { "OPENAI_ADS_API_KEY": "your-openai-ads-api-key" } } } }

Add to.vscode/mcp.json. VS Code can prompt for the key and store it as a secret viainputs:

{ "inputs": [ { "type": "promptString", "id": "openai_ads_api_key", "description": "OpenAI Ads API key", "password": true } ], "servers": { "openai-ads": { "command": "npx", "args": ["-y", "@hypd-ai/openai-ads-mcp"], "env": { "OPENAI_ADS_API_KEY": "${input:openai_ads_api_key}" } } } }

Any client that speaks MCP overstdioworks. Runnpx -y @hypd-ai/openai-ads-mcp(ornode /path/to/dist/index.js) withOPENAI_ADS_API_KEYset in the environment.

Fields whose names end in_micros— for example a campaign'slifetime_spend_limit_microsor an ad group'smax_bid_micros— are expressed in micros:

1,000,000 micros = 1 unit of the account's currency (e.g. $1.00 = 1,000,000 micros)

So alifetime_spend_limit_microsof25000000is$25.00. Divide a_microsvalue by 1,000,000 to display a human amount, or multiply by 1,000,000 to convert the other way.

Insights metrics are not micros.Reporting values likespend,cpc, andcpmare already in the account's currency as decimals (e.g.spend: 42.75means $42.75).

This release registersonly read (GET) tools— and each one is annotated with the MCPreadOnlyHint, so well-behaved clients know it cannot mutate state. There is no tool here that can create, edit, pause, or delete anything, and nothing that can spend budget. Write actions will arrive as a deliberate, separately reviewed step (seeRoadmap).

git clone https://github.com/hypd-ai/openai-ads-mcp.git cd openai-ads-mcp npm install npm run build

{ "mcpServers": { "openai-ads": { "command": "node", "args": ["/absolute/path/to/openai-ads-mcp/dist/index.js"], "env": { "OPENAI_ADS_API_KEY": "your-openai-ads-api-key" } } } }

OPENAI_ADS_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

npm install # install dependencies npm run dev # rebuild on change (tsup --watch) npm run typecheck # tsc --noEmit npm run lint # eslint npm run format # prettier --write npm test # vitest npm run build # bundle to dist/

src/ index.ts # bin entry: load config, build server, connect stdio server.ts # buildServer(): McpServer + register all tools client.ts # OpenAIAdsClient: auth, URL building, errors config.ts # environment parsing & validation schemas.ts # shared zod shapes (pagination, insights) + micros note tools/ # one file per resource (account, campaigns, ad-groups, ads, insights) test/ # vitest specs (config, client, in-memory server)

All endpoints are under the base URL (defaulthttps://api.ads.openai.com/v1).

- ✍️Write actions— create & update (viaPOST) campaigns, ad groups, and ads, plus the dedicated state transitions (POST .../activate,.../pause,.../archive). The HTTP client already supportsPOST; these will be gated behind an explicit opt-in, since they change delivery and spend.
- 🖼️Creative uploads—POST /upload(JSONimage_urlormultipart/form-data) to attach images to ad creatives.
- 🌍Campaign targeting— country include/exclude (targeting.locations.countries).
- 📈Conversions APIsupport.
- 🌐Remote/HTTP transportfor hosted deployments.
- 📦Published npm releasesonpx -y openai-ads-mcpworks out of the box.

Contributions are welcome! Please readCONTRIBUTING.md. In short: open an issue to discuss substantial changes, keepnpm run lint && npm run typecheck && npm testgreen, and add tests for new behavior.

This is anunofficial, community-built project. It isnot affiliated with, endorsed by, or sponsored by OpenAI. "OpenAI" and related names and logos are trademarks of OpenAI. Your use of the OpenAI Ads API through this tool is subject to OpenAI's terms and policies. The tool is provided "as is", without warranty of any kind — see thelicense.

Perplexity for social: ask what competitors are running across social and get answers grounded in real ad and creative data, not guesses.