Show HN: MCP for the ChatGPT Ads API – Query ChatGPT Ads from Claude and Codex

Notifications You must be signed in to change notification settings

Fork 1

Star 2

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

17 Commits

17 Commits

.github/workflows

.github/workflows

src

src

test

test

.env.example

.env.example

.gitignore

.gitignore

.prettierignore

.prettierignore

.prettierrc.json

.prettierrc.json

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

eslint.config.js

eslint.config.js

package-lock.json

package-lock.json

package.json

package.json

server.json

server.json

tsconfig.json

tsconfig.json

tsup.config.ts

tsup.config.ts

vitest.config.ts

vitest.config.ts

Repository files navigation

A Model Context Protocol (MCP) server for the OpenAI 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 only reads data — it never creates, edits, or pauses anything and never spends budget. Write actions are on the roadmap.

Unofficial. This is a community project and is not affiliated with or endorsed by OpenAI. See the disclaimer.

Overview

The OpenAI Ads API exposes 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:

"Is my OpenAI Ads API key working? What account is it tied to?"

"List my active campaigns and their budgets."

"Show spend, clicks, and CTR for campaign cmp_123 over the last 30 days, by day."

"Which ads in ad group adg_456 are still pending review?"

Features

11 read-only tools covering 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 the micros convention so the assistant can present human-readable currency.

Cursor pagination passthrough (limit, order, after, before).

Zero-install via npx — npx -y @hypd-ai/openai-ads-mcp, no clone or build.

Tools

Tool What it does

get_ad_account Fetch the ad account for the configured key. Great as a connectivity check.

list_campaigns List campaigns (objective, budget, country targeting).

get_campaign Fetch a single campaign by ID.

list_ad_groups List ad groups, optionally filtered by campaign.

get_ad_group Fetch a single ad group by ID (bidding config, context hints).

list_ads List ads, optionally filtered by ad group.

get_ad Fetch a single ad by ID (creative + review status).

get_account_insights Performance insights for the whole account.

get_campaign_insights Performance insights for one campaign.

get_ad_group_insights Performance insights for one ad group.

get_ad_insights Performance insights for one ad.

Insights tools accept since/until (YYYY-MM-DD) for the reporting window, plus time_granularity (daily/none), aggregation_level, fields, sort, filters, limit (1–10000), and after/before cursors.

Prerequisites

Node.js 20 or newer.

An OpenAI Ads API key. Create an Ads account at ads.openai.com (currently US-only), then issue a key from Settings → ads.openai.com/settings. See the quickstart and authentication docs. Each key is scoped to a single ad account.

Installation & configuration

MCP clients launch the server as a subprocess and pass your API key via an environment variable.

Published on npm as @hypd-ai/openai-ads-mcp — npx fetches it for you, so there's nothing to clone or build. To run the latest unreleased main instead, replace @hypd-ai/openai-ads-mcp with github:HYPD-AI/openai-ads-mcp (its first launch builds from source — see Running from source).

Add the snippet for your client below.

Claude Desktop

Edit your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "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."

Cursor

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" } } } }

VS Code

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

{ "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}" } } } }

Other MCP clients

Any client that speaks MCP over stdio works. Run npx -y @hypd-ai/openai-ads-mcp (or node /path/to/dist/index.js) with OPENAI_ADS_API_KEY set in the environment.

Configuration

Variable Required Default Description

OPENAI_ADS_API_KEY Yes — Your OpenAI Ads API key, sent as a Bearer token.

OPENAI_ADS_BASE_URL No https://api.ads.openai.com/v1 Override the API base URL (useful for testing or a proxy).

See .env.example.

A note on "micros"

Fields whose names end in _micros — for example a campaign's lifetime_spend_limit_micros or an ad group's max_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 a lifetime_spend_limit_micros of 25000000 is $25.00. Divide a _micros value 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 like spend, cpc, and cpm are already in the account's currency as decimals (e.g. spend: 42.75 means $42.75).

Read-only by design

This release registers only read (GET) tools — and each one is annotated with the MCP readOnlyHint, 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 (see Roadmap).

Running from source

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

Then point your MCP client at the built entry file:

{ "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" } } } }

Try it with the MCP Inspector

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

Development

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/

Project layout:

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)

How tools map to the API

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

Tool Method Endpoint

get_ad_account GET /ad_account

list_campaigns GET /campaigns

get_campaign GET /campaigns/{campaign_id}

list_ad_groups GET /ad_groups

get_ad_group GET /ad_groups/{ad_group_id}

list_ads GET /ads

get_ad GET /ads/{ad_id}

get_account_insights GET /ad_account/insights

get_campaign_insights GET /campaigns/{campaign_id}/insights

get_ad_group_insights GET /ad_groups/{ad_group_id}/insights

get_ad_insights GET /ads/{ad_id}/insights

Roadmap

✍️ Write actions — create & update (via POST) campaigns, ad groups, and ads, plus the dedicated state transitions (POST .../activate, .../pause, .../archive). The HTTP client already supports POST; these will be gated behind an explicit opt-in, since they change delivery and spend.

🖼️ Creative uploads — POST /upload (JSON image_url or multipart/form-data) to attach images to ad creatives.

🌍 Campaign targeting — country include/exclude (targeting.locations.countries).

📈 Conversions API support.

🌐 Remote/HTTP transport for hosted deployments.

📦 Published npm release so npx -y openai-ads-mcp works out of the box.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md. In short: open an issue to discuss substantial changes, keep npm run lint && npm run typecheck && npm test green, and add tests for new behavior.

Disclaimer

This is an unofficial, community-built project. It is not 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 the license.

License

MIT © HYPD AI

About

MCP server for OpenAI Ads / ChatGPT Ads. Manage campaigns, ad groups, ads, creatives, and insights through the OpenAI Ads Advertiser API.

www.hypd.ai/

Topics

chatgpt

mcp-server

chatgpt-ads

openai-ads

Resources

Readme

License

MIT license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity

Custom properties

Stars

2 stars

Watchers

0 watching

Forks

1 fork

Report repository

Releases 2

v0.1.1 — now on npm

Latest

Jun 3, 2026

+ 1 release

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

TypeScript 96.8%

JavaScript 3.2%