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: facebook-business-mcp

Quick start

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

Claude Code — one command, done:

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

Claude Desktop / other MCP clients — add to your config (.mcp.json, claude_desktop_config.json, etc.):

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

That's it — one env var. No key yet? Skip it: the server starts fine and the four offline tools work; only network-backed tools need the key.

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 / -e 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.