LABSCO SUMMARY

Nothing you create can start spending, because creation and activation are different tools.

Campaigns and ad groups are created paused, the whole-tree builder builds paused, and the A/B variants arrive paused too — going live means calling the state tools afterwards, on purpose. Budget carries a second guard on top of that: a change is checked against a configured ceiling and needs an explicit confirmation. The rest of the limits are stated rather than discovered at runtime — name lengths, minimum budgets, page sizes, bounded start times and a conversion batch cap all appear in the tool descriptions.

What it is

A full client for the OpenAI Ads API — campaigns, ad groups, ads, creatives, audiences, geo targeting, conversions and reporting — shaped so that nothing it creates can spend money until a separate call activates it. It runs locally under either a Python or a Node runtime, and a hosted read-only endpoint exists for discovery.

What you get

get_account, which verifies the key and returns the ad account's id, name, timezone, currency and settings — the first call to make.
The whole tree with matching list, get, create and update tools: campaigns carrying a lifetime budget, ad groups with a billing event of impression or click and a maximum bid, and ads carrying a creative.
build_campaign, which creates one campaign, one ad group and several ads in a single guarded workflow with everything paused, and returns whatever was created plus the error when a step fails.
Activation as its own decision: set_campaign_state, set_ad_group_state and set_ad_state each activate, pause or archive, and each states that activation can start real spend or delivery once the rest of the tree is active.
Creatives through upload_creative, which takes exactly one of a URL or a local file and returns a file id, and create_ad, which builds a chat card from a target URL and that file, or a product ad template.
bulk_ab_test_hints, which creates several paused variants under one ad group, and draft_context_hints, which composes targeting hints deterministically from an audience, intent, keywords and product with no external model call.
get_insights, the reporting tool, returning impressions, clicks, spend, CTR, CPC, CPM and conversions at account, campaign, ad group or ad scope, with segments, granularity and a time range.
Audiences and targeting: list_audiences and get_audience, manage_audience to create one from members, upload one from a file or archive it, and search_geo, which returns the geo and DMA ids to pass into a campaign's targeting.
Conversion setup in one tool — manage_conversions creates pixels and API keys, reads and sets event settings with an attribution window, and reads conversion insights — plus send_conversions, which posts events to the ingest host, validates the batch cap and the timestamp window, and never logs the user data in them.

Requirements

An OpenAI Ads API key in OPENAI_ADS_API_KEY, and a runtime — the same server ships for uvx and for npx, so take whichever your machine already has. Two guards are worth setting before an agent touches this: OPENAI_ADS_MCP_READONLY registers the read tools only, and OPENAI_ADS_BUDGET_CEILING_USD caps what a budget change is allowed to become. A hosted read-only endpoint exists for discovery, and it never holds anyone's key: a caller must send their own on each Ads call.

Setup effort

One command plus a key — uvx openai-ads-mcp, then supply credentials

See installation options

USE CASES

01

Getting a campaign built without it going live

Build the campaign, ad group and ads in one guarded call — everything arrives paused, and a failed step reports what was created before it.

build_campaignupload_creative

02

Reviewing the tree and only then turning it on

Read back the campaign, ad group and ads, check the budget, and activate each level deliberately.

get_campaignlist_adsset_campaign_stateset_ad_state

03

Reading what the spend actually bought

Pull impressions, clicks, spend, CTR, CPC and CPM at whichever scope the question is about, segmented and over a window.

get_insights

04

Running an A/B test on ad copy

Create the variants under one ad group in a single call, all paused, then compare them once they have run.

bulk_ab_test_hintsget_insights

05

Pointing a campaign at a place and a list of people

Look up the geo ids for the locations, build or upload the custom audience, and set both on the campaign.

search_geomanage_audienceupdate_campaign

06

Wiring conversion tracking and feeding it events

Create the pixel and its key, set the attribution window, then post the events in validated batches.

manage_conversionssend_conversions

07

Letting an agent look but not touch

Register the server in read-only mode so the write tools never appear, and keep the budget ceiling set for when they do.

get_accountlist_campaignsget_insights

27 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`build_campaign`

Build a complete paused campaign tree in one guarded workflow.

Creates one campaign, one ad group, and N ads. Everything is created paused. If a step fails, the response includes whatever was created so far plus the error so you can clean up or continue deliberately.

ad_group must be an object with name, billing_event, and max_bid_usd. It may include context_hints. ads must be a list of objects accepted by create_ad: name, creative_type, title, body, target_url, file_id, and optional price.

BEFORE YOU INSTALL

What to know first

Tools you get

27 tools when we connected. Every documented install snippet sets OPENAI_ADS_MCP_READONLY, which hides all write tools, roughly half the set. Remote mode forces read-only unless OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1, and OPENAI_ADS_BUDGET_CEILING_USD defaults to 100.

Requires

uvx on PATH
OPENAI_ADS_API_KEY in your environment

CONTEXT COST

Moderate Standing cost

Rated by the size of the 27 tool definitions that ride along on every turn, not by how many there are

INSTALLATION

Connect your client

Server setup

uvx

TERMINAL

uvx openai-ads-mcp

Hosted endpoint

ENDPOINT URL

https://openai-ads-mcp.trakkr.ai/mcp

Add this hosted endpoint to your MCP client using the credentials listed under Requirements.

MCP Clients

Claude Code — Python

CLAUDE CODE — PYTHON · TERMINAL

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=<YOUR_OPENAI_ADS_API_KEY> \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- uvx openai-ads-mcp

Claude Code — Node

CLAUDE CODE — NODE · TERMINAL

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=<YOUR_OPENAI_ADS_API_KEY> \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- npx -y openai-ads-mcp

Cursor, Claude Desktop

JSON

{
  "mcpServers": {
    "openai-ads": {
      "command": "uvx",
      "args": [
        "openai-ads-mcp"
      ],
      "env": {
        "OPENAI_ADS_API_KEY": "<YOUR_OPENAI_ADS_API_KEY>",
        "OPENAI_ADS_MCP_READONLY": "1"
      }
    }
  }
}

Codex

CODEX · TOML

[mcp_servers.openai_ads]
command = "uvx"
args = ["openai-ads-mcp"]
env = { OPENAI_ADS_API_KEY = "<YOUR_OPENAI_ADS_API_KEY>", OPENAI_ADS_MCP_READONLY = "1" }

Docker

DOCKER · TERMINAL

git clone https://github.com/trakkr-aisearch/openai-ads-mcp.git
cd openai-ads-mcp
docker build -t openai-ads-mcp .
docker run --rm -p 8080:8080 \
  -e OPENAI_ADS_MCP_HOSTED_PUBLIC=1 \
  -e OPENAI_ADS_MCP_TELEMETRY_SALT="local-test-salt" \
  openai-ads-mcp

Self-run HTTP server

SELF-RUN HTTP SERVER · TERMINAL

export OPENAI_ADS_MCP_HTTP_TOKEN="choose_a_long_random_token"
export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp --http

OpenAI Ads MCP Server

Nothing you create can start spending, because creation and activation are different tools.

What it is

What you get

Requirements

Setup effort

Getting a campaign built without it going live

Reviewing the tree and only then turning it on

Reading what the spend actually bought

Running an A/B test on ad copy

Pointing a campaign at a place and a list of people

Wiring conversion tracking and feeding it events

Letting an agent look but not touch

27 tools

build_campaign

bulk_ab_test_hints

create_ad

create_ad_group

create_campaign

draft_context_hints

get_account

get_ad

get_ad_group

get_audience

get_campaign

get_insights

list_ad_groups

list_ads

list_audiences

list_campaigns

manage_audience

manage_conversions

search_geo

send_conversions

set_ad_group_state

set_ad_state

set_campaign_state

update_ad

update_ad_group

update_campaign

upload_creative

What to know first

Tools you get

Requires

Moderate Standing cost

Connect your client

Server setup

uvx

Hosted endpoint

MCP Clients

Claude Code — Python

Claude Code — Node

Cursor, Claude Desktop

Codex

Docker

Self-run HTTP server

Same category

OpenAI Ads Reporting

OrbiAds

Mailchimp MCP

TikTok for Business MCP Server

`build_campaign`

`bulk_ab_test_hints`

`create_ad`

`create_ad_group`

`create_campaign`

`draft_context_hints`

`get_account`

`get_ad`

`get_ad_group`

`get_audience`

`get_campaign`

`get_insights`

`list_ad_groups`

`list_ads`

`list_audiences`

`list_campaigns`

`manage_audience`

`manage_conversions`

`search_geo`

`send_conversions`

`set_ad_group_state`

`set_ad_state`

`set_campaign_state`

`update_ad`

`update_ad_group`

`update_campaign`

`upload_creative`