OpenAI Ads MCP Server (read + write)

An MCP server for ads in ChatGPT, using the OpenAI Ads Advertiser API. Use it from Claude, ChatGPT, Cursor, Codex or any MCP client to build and change campaigns, ad groups and ads, manage budgets, bids, targeting, audiences, conversion tracking and product feeds, and report on performance.

It is maintained by AI Shopping Feeds and offers:

• The whole documented Advertiser API v1: account and spending limits, campaigns, ad groups, ads and previews, uploads, custom audiences, conversion setup, insights, product feeds, Bulk API jobs and lead sync.

• Safety: dry-run, confirm words for archives, deletes, activations and bid or budget rises, paused-by-default creation, spend caps, an audit log with before-snapshots, read-only mode and tool groups.

• Anything else through a read-only and a confirm-gated raw request tool.

OpenAI doesn't publish an MCP server for OpenAI Ads; its own tools are Ads Manager and this API. This one runs on your machine with your own Ads API key. The Advertiser API and Ads Manager are in beta and change often: see docs/terms-and-data.md. Not affiliated with or endorsed by OpenAI.

Part of the AI Shopping Feeds MCP family: Google Ads · Google Merchant Centre · Google Analytics · YouTube Studio · Amazon Ads · Apple Ads · Microsoft Ads · TikTok Ads · Pinterest Ads · Snapchat Ads · OpenAI Ads · AppLovin.

Let your agent set it up

Paste this into Claude Code, Codex, Cursor or any agent that can read web pages and edit files:

Set up the OpenAI Ads MCP server for me by following https://raw.githubusercontent.com/AI-Shopping-Feeds/openai-ads-mcp/main/skills/openai-ads-mcp/SKILL.md

The agent checks whether it's already connected, installs the runner if you agree, walks you through creating an Ads API key and storing it, adds the server to your client's config without touching your other servers, and checks it works by calling openai_ads_health_check.

The same file is an Agent Skill, so your agent can keep it as a guide to using the tools well. For Claude Code, copy the folder into your skills:

git clone --depth 1 https://github.com/AI-Shopping-Feeds/openai-ads-mcp.git /tmp/openai-ads-mcp
cp -r /tmp/openai-ads-mcp/skills/openai-ads-mcp ~/.claude/skills/

Other agents that support skills load the same skills/openai-ads-mcp folder from their own skills directory.

Related MCP server: openai-ads-mcp

What it can do

76 tools, all prefixed openai_ads_. The full list is in docs/tools.md.

Read

Write

Safety

• Dry-run (OPENAI_ADS_DRY_RUN=true or openai_ads_set_dry_run) logs writes without sending them.

• Paused by default: new campaigns, ad groups and ads start paused; creating or activating anything live needs confirm='APPLY'.

• Confirm words: ARCHIVE for archives, DELETE for deletes, and APPLY for more than 10 items, budget, bid or spend-limit rises above 20% (OPENAI_ADS_MAX_INCREASE_PCT) or whose current value can't be read, values over optional caps, Maximize Results switches and raw writes.

• Audit log of every write with a before-snapshot (~/.openai-ads-mcp/logs/audit.jsonl), kept 30 days (OPENAI_ADS_AUDIT_RETENTION_DAYS); openai-ads-mcp purge deletes it and the stored key.

• Read-only mode (OPENAI_ADS_READ_ONLY=true) and tool groups (OPENAI_ADS_TOOL_GROUPS).

• Secrets stay out of chat: Conversions API keys, SFTP passwords and signing secrets go to owner-only files; audience identifiers never reach the audit log.

• Refuses to bind its HTTP transports to anything but localhost unless OPENAI_ADS_ALLOW_REMOTE=true.

• What OpenAI's terms allow and how data is handled: docs/terms-and-data.md.

Supported clients

Setup

1. Install uv

The server runs with uvx from uv (brew install uv on macOS) and needs Python 3.11 or later. It installs straight from this repository:

uvx --from git+https://github.com/AI-Shopping-Feeds/openai-ads-mcp.git openai-ads-mcp

Pin a release by adding @vX.Y.Z to the URL.

2. Get credentials

1. Ads Manager: you need an OpenAI Ads account at ads.openai.com with self-service access in your country, and admin access to it.

2. Ads API key: in Ads Manager go to Settings → General → API keys and create a key. It's an Ads API key, not an OpenAI platform key. Step by step: docs/setup-openai-ads-api.md.

3. Store it (it is checked against the API and saved with owner-only permissions in ~/.openai-ads-mcp/secrets/):

   uvx --from git+https://github.com/AI-Shopping-Feeds/openai-ads-mcp.git openai-ads-mcp auth

3. Add it to your client

Replace the placeholders. Keep your other servers in each file. With a key stored by auth you need no env at all; the examples add dry-run for a safe first run.

Claude Code

claude mcp add --scope user openai-ads \
  --env OPENAI_ADS_DRY_RUN=true \
  --env OPENAI_ADS_UPLOAD_DIR=/abs/path/ad-assets \
  -- uvx --from git+https://github.com/AI-Shopping-Feeds/openai-ads-mcp.git openai-ads-mcp

Claude Desktop, Cursor, Gemini CLI, Windsurf (and VS Code under servers)

{
  "mcpServers": {
    "openai-ads": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AI-Shopping-Feeds/openai-ads-mcp.git", "openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_DRY_RUN": "true",
        "OPENAI_ADS_UPLOAD_DIR": "/abs/path/ad-assets"
      }
    }
  }
}

Desktop apps often can't find uvx on the PATH; if the server doesn't start, use the full path from which uvx as the command.

Codex (~/.codex/config.toml)

[mcp_servers.openai-ads]
command = "uvx"
args = ["--from", "git+https://github.com/AI-Shopping-Feeds/openai-ads-mcp.git", "openai-ads-mcp"]
env = { OPENAI_ADS_DRY_RUN = "true", OPENAI_ADS_UPLOAD_DIR = "/abs/path/ad-assets" }

To manage several ad accounts, add one server entry per account, each with its own key (OPENAI_ADS_KEY_FILE=/abs/path/client-a-key.json, written by auth --output).

4. Check it works

Restart or reload the client, then ask it to "check my OpenAI Ads connection". It should call openai_ads_health_check and show the ad account's currency, timezone and review status.

Configuration

Settings are read from the environment, then --env or ./.env, then ~/.openai-ads-mcp/.env. A full example is in .env.example.

Example prompts

Show spend, clicks and CTR by campaign for the last 14 days, and flag any campaign with serving issues.

Create a paused clicks campaign called "Example spring launch" in the US with a 50 daily budget, one ad group with a 1.50 max bid and context hints about trail running shoes, and an ad using the image at https://example.com/shoe.jpg. Do a dry run first.

Lower the max bid by 15% on every ad group in campaign cmpn_123 whose CTR was below 0.5% last week.

Check why ad ad_123 isn't serving: review status, serving issues, parent statuses, budget and account spend limits.

More docs

• All tools

• Getting OpenAI Ads API access

• Terms, data handling and brand use

• Agent skill: setup and usage guide for agents

• Changelog and security policy

Contributing and licence

Issues and pull requests are welcome on this repository. See CONTRIBUTING.md.

Licensed under the MIT License. "OpenAI" and "ChatGPT" are trademarks of OpenAI, used here only to describe the API this software works with.

Try out AI Shopping Feeds, our shopping feed management tool (including Google Shopping feeds).