OpenAI Ads MCP

A Model Context Protocol server for OpenAI's ChatGPT Ads platform — read campaigns/ad groups/ads, pull insights, draft optimization plans, and apply approval-gated live mutations. Built for use from Claude, OpenClaw, Hermes, or any MCP-compatible agent.

Safety model

• API keys come from environment variables only — never hardcoded, never in source. A key pasted into a chat or log should be considered compromised; rotate it.

• Read / report / draft tools are available by default and are non-destructive.

• Live mutations are double-gated. A write executes only when both are true:

  • OPENAI_ADS_ENABLE_WRITES=1, and

  • a matching approval artifact exists at tasks/openai-ads/approvals/<id>.json inside this repo (shape below) whose declared budget/countries/destructiveness bound the operation.

• Every mutation is audit-logged to tasks/openai-ads/audit.jsonl (gitignored).

Approval/audit paths resolve relative to this package's directory by default; override with OPENAI_ADS_REPO_ROOT, OPENAI_ADS_APPROVAL_DIR, or OPENAI_ADS_AUDIT_LOG.

Related MCP server: flour-ads

Quick start

First, clone and install (all three clients need this). Requires Bun — curl -fsSL https://bun.sh/install | bash.

git clone https://github.com/adityash8/openai-ads-mcp.git
cd openai-ads-mcp
bun install

One env var is all you need: OPENAI_ADS_PRIMARY_API_KEY. No key yet? Skip it — the server starts fine and the four offline tools work; only the network-backed tools need a key. Then pick your client below.

Claude Code

From inside the cloned directory, one command ($PWD expands to the absolute path at add-time):

claude mcp add --env OPENAI_ADS_PRIMARY_API_KEY=YOUR_KEY --transport stdio openai-ads -- bun "$PWD/index.ts"

This registers it for the current project. Add --scope user (before the openai-ads name) to make it available in every project. Verify with claude mcp list, then use it in a session: "list my OpenAI Ads campaigns."

Claude Desktop

Edit the config file (Settings → Developer → Edit Config, or directly):

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

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server (use the absolute path to index.ts), then fully quit and reopen Claude Desktop:

{
  "mcpServers": {
    "openai-ads": {
      "command": "bun",
      "args": ["/absolute/path/to/openai-ads-mcp/index.ts"],
      "env": {
        "OPENAI_ADS_PRIMARY_API_KEY": "YOUR_KEY"
      }
    }
  }
}

The tools appear under the 🔌 / tools menu once the server connects.

ChatGPT

1. Bridge stdio → SSE with supergateway:

   OPENAI_ADS_PRIMARY_API_KEY=YOUR_KEY \
     npx -y supergateway --stdio "bun index.ts" --port 8000 --ssePath /sse

2. Expose it over HTTPS with a tunnel (ChatGPT must reach it from the internet) — e.g. cloudflared or ngrok:

   cloudflared tunnel --url http://localhost:8000   # prints an https://… URL

3. Add the connector in ChatGPT: Settings → Apps → Advanced → Developer mode (enable) → Create app. Set the MCP server URL to your tunnel's https://…/sse endpoint. It lands under "Drafts," then is callable in chat.

Configuration details

• Multiple ad accounts: each account is an uppercase account key; its key is read from OPENAI_ADS_<ACCOUNT_KEY>_API_KEY (e.g. add OPENAI_ADS_BRANDX_API_KEY and pass account_key: "BRANDX" in tool calls). The default account key is PRIMARY; change it with OPENAI_ADS_DEFAULT_ACCOUNT.

• Writes are off by default. Set OPENAI_ADS_ENABLE_WRITES=1 and supply an approval artifact (below) to enable mutations.

• Pass env vars through your MCP client config (the env block / --env flag), as shown above. A local .env works too, but only when running under Bun from this directory — node dist/index.js and MCP clients launched from other working directories won't read it.

• Prefer a Node runtime? bun run build once, then point your client at node /absolute/path/to/openai-ads-mcp/dist/index.js (Node 18+). Bun is still required for build/test — plain Node can't run the TypeScript source.

Tools

Approval artifact shape

operations must contain at least one entry. Valid operation types: create_campaign, update_campaign, campaign_state, create_ad_group, update_ad_group, ad_group_state, create_ad, update_ad, ad_state. State operations take { "id": "...", "action": "activate" | "pause" | "archive" }.

{
  "id": "example-approval",
  "account_key": "PRIMARY",
  "approved_by": "you",
  "approved_at": "2026-06-02T00:00:00.000Z",
  "max_budget_micros": 10000000,
  "approved_countries": ["US"],
  "allow_destructive": false,
  "operations": [
    { "type": "ad_state", "id": "ad_123", "action": "pause" }
  ]
}

Conversion event shape

openai_ads_validate_conversion_event expects:

{
  "type": "order_created",
  "timestamp_ms": 1764547200000,
  "data": {}
}

type must be one of: appointment_scheduled, checkout_started, contents_viewed, custom, items_added, lead_created, order_created, page_viewed, registration_completed, subscription_created, trial_started. id, timestamp_ms, and metadata are optional.

Develop

bun test          # offline — uses a mocked Ads client
bun run build     # bundle index.ts -> dist/ (Node target)

Live read-only probe

After setting a real key, verify connectivity without changing anything:

bun run probe:live -- --account PRIMARY

Checks the ad account, campaign listing, and account insights. For insights, time_granularity is none or daily (all / day are accepted aliases and normalized). Metric arrays encode as fields[]=impressions&fields[]=clicks.

License

MIT © 2026 Aditya Sheth. See LICENSE.