mcp-openai-ads

An open-source Model Context Protocol (MCP) server for the OpenAI Ads (ads in ChatGPT) Advertiser API.

It lets an AI assistant such as Claude Desktop, Claude Code, Cursor or VS Code read your ChatGPT Ads account, report on performance and, if you allow it, manage campaigns, ad groups and ads.

Community project by PPC Blog Pro. Not affiliated with or endorsed by OpenAI.

Features

• Read-only by default. Write tools are only registered when you set OPENAI_ADS_ALLOW_WRITES=true.

• Dry run first. Every write returns a preview until it is called again with confirm: true, and updates report a before/after diff.

• New entities start paused, so nothing spends money until you activate it.

• Money in plain currency units. You say daily_budget: 50 and the server converts it to the API's micros.

• Compact markdown tables, which keep token use low.

• Retries with backoff on 429 and 5xx responses, respecting Retry-After. Create calls send an Idempotency-Key.

Related MCP server: Ads Analytics MCP

Tools

Write tools (require OPENAI_ADS_ALLOW_WRITES=true):

Prompts: weekly_performance_review, find_underperformers, diagnose_not_serving.

Setup

1. Get an API key

1. Open OpenAI Ads Manager, then go to Settings.

2. Create an Advertiser API key. It is tied to one ad account.

See OpenAI's Advertiser API overview for details.

2. Add the server to your MCP client

Requires Node.js 20 or later.

Claude Desktop: edit claude_desktop_config.json:

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

On Windows, if npx isn't found, use "command": "cmd" and "args": ["/c", "npx", "-y", "mcp-openai-ads"].

Claude Code:

claude mcp add openai-ads -e OPENAI_ADS_API_KEY=your-key -- npx -y mcp-openai-ads

Cursor: use the same JSON as Claude Desktop, in ~/.cursor/mcp.json.

VS Code: add this to .vscode/mcp.json:

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

Configuration

Example prompts

• "Give me a summary of my ChatGPT Ads account for the last 14 days."

• "Show daily clicks and spend for campaign Fall Sale this month, split by device."

• "Which ads have the lowest CTR? Suggest better copy."

• "Why isn't my new campaign serving?"

• (with writes enabled) "Raise the daily budget of Fall Sale to 80 and show me the change before applying it."

Safety notes

• The API key has full access to its ad account. Keep it in your MCP client's env block, never in a repo.

• The server logs only to stderr and never logs the key.

• Leave writes disabled unless you need them. When they are enabled, your AI client should still ask before calling a tool with confirm: true.

Releasing (maintainers)

1. Bump version in both package.json and server.json (a test enforces that they match), and update CHANGELOG.md.

2. Commit, then git tag vX.Y.Z && git push --tags.

3. The Release workflow publishes to npm and to the MCP Registry as io.github.dienhokhanh/mcp-openai-ads.

Development

npm install
npm run build
npm test
npm run inspect   # opens the MCP Inspector against dist/index.js

To run from source in a client, point it at node /path/to/repo/dist/index.js.

The API client is in src/client.ts, and tools live in src/tools/ as read.ts, insights.ts and write.ts. The OpenAI Ads API is new, so if an endpoint changes, please open an issue or PR.

Author

Built and maintained by PPC Blog Pro, which publishes PPC and paid-ads guides, tips and tools.

License

MIT