io.github.trakkr-aisearch/openai-ads-mcp

Official

by trakkr-aisearch · TypeScript

OpenAI Ads MCP

OpenAI and ChatGPT Ads tools for campaigns, creatives, audiences, and insights.

Manages OpenAI and ChatGPT ad campaigns, creatives, audiences, and performance insights.

Topics

adsadvertisingmcpopenaitrakkrai-searchchatgpt-adsmcp-servermodel-context-protocoladvertiser-api

README.md11 KBView on GitHub

openai-ads-mcp

Trakkr tracks the full AI-visibility funnel, organic and paid. This is the open-source paid-side companion.

openai-ads-mcp is a typed Model Context Protocol server for OpenAI Ads, ChatGPT Ads, and OpenAI's Advertiser API. It lets Claude, Cursor, Codex, VS Code, and other MCP clients inspect Ads accounts, read performance insights, build paused campaigns, upload creatives, manage audiences, and send conversion events.

It ships in two runtimes with the same tool names, arguments, defaults, safety model, and vendored OpenAPI reference:

Runtime	Best install	Package path
Python	`uvx openai-ads-mcp`	`python/`
Node	`npx -y openai-ads-mcp`	`typescript/`

The goal is simple: make OpenAI Ads workable from an AI assistant without making spend easy to trigger by accident.

Install

Python with uvx:

bash

uvx openai-ads-mcp

Python with pip:

bash

python -m pip install openai-ads-mcp
openai-ads-mcp

Node with npx:

bash

npx -y openai-ads-mcp

Node with npm:

bash

npm install -g openai-ads-mcp
openai-ads-mcp

For local development from this monorepo:

bash

cd services/openai-ads-mcp/python
python -m pip install -e .
python -m openai_ads_mcp

cd ../typescript
npm install
npm run build
node dist/index.js

Configuration

Create an Ads API key in OpenAI Ads Manager, then pass it as an environment variable.

bash

export OPENAI_ADS_API_KEY="..."

Recommended first connection:

bash

export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

Or with Node:

bash

export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp

Readonly mode hides every write tool. They are absent from tools/list and cannot be called. Once you have confirmed the account and inspected data, unset OPENAI_ADS_MCP_READONLY to enable writes.

Optional environment variables:

Variable	Purpose
`OPENAI_ADS_API_KEY`	Required bearer key for `https://api.ads.openai.com/v1`.
`OPENAI_ADS_API_BASE_URL`	Optional HTTPS override for tests or proxies.
`OPENAI_ADS_MCP_READONLY`	Set to `1` or `true` to register read tools only.
`OPENAI_ADS_BUDGET_CEILING_USD`	Optional budget guard. Default `100`.

Discovery Metadata

This repo includes server.json for the official MCP Registry and downstream MCP directories. The canonical registry name is:

text

io.github.trakkr-aisearch/openai-ads-mcp

The Node package includes the matching mcpName, and the Python package README includes the matching mcp-name marker for PyPI ownership verification.

The registry metadata also advertises the hosted read-only Streamable HTTP endpoint:

text

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

That hosted endpoint is for discovery and read-only usage. It does not store or use a Trakkr-owned OpenAI Ads API key.

MCP client examples

Claude Code, Python runtime

bash

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=your_ads_key_here \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- uvx openai-ads-mcp

Claude Code, Node runtime

bash

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=your_ads_key_here \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- npx -y openai-ads-mcp

Cursor or Claude Desktop

json

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

Use "command": "npx" and "args": ["-y", "openai-ads-mcp"] for the Node runtime.

Codex CLI

toml

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

Docker

The repository includes production Dockerfiles for hosted Streamable HTTP deployments:

bash

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

The narrower typescript/Dockerfile is used by the Cloud Run deploy script. For local stdio use, prefer uvx openai-ads-mcp or npx -y openai-ads-mcp.

Streamable HTTP

The Node runtime can also serve MCP over Streamable HTTP for hosted or team deployments:

bash

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

Defaults:

URL: http://127.0.0.1:8080/mcp locally, or https://your-host/mcp behind a proxy.
Health check: GET /healthz.
Remote mode forces OPENAI_ADS_MCP_READONLY=1 unless OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1 is set.
OPENAI_ADS_MCP_HTTP_TOKEN protects the MCP endpoint with Authorization: Bearer <token>.
Clients may send X-OpenAI-Ads-API-Key per request, or the server can use a server-side OPENAI_ADS_API_KEY.

Useful hosted env vars:

Variable	Purpose
`PORT` or `OPENAI_ADS_MCP_HTTP_PORT`	HTTP port. Default `8080`.
`OPENAI_ADS_MCP_HTTP_PATH`	MCP path. Default `/mcp`.
`OPENAI_ADS_MCP_HEALTH_PATH`	Health path. Default `/healthz`.
`OPENAI_ADS_MCP_HTTP_TOKEN`	Optional bearer token required by hosted clients.
`OPENAI_ADS_MCP_HTTP_ALLOW_WRITES`	Set to `1` only when you want write tools exposed over HTTP.
`OPENAI_ADS_MCP_HTTP_CORS_ORIGIN`	Optional CORS origin. Default `*`.

For public hosted endpoints, keep writes disabled by default and inject Ads API keys server-side through your own OAuth or credential vault. Do not put a shared Ads API key in browser-visible config.

Public hosted mode

For a public discovery endpoint, use:

bash

export OPENAI_ADS_MCP_HOSTED_PUBLIC=1
export OPENAI_ADS_MCP_TELEMETRY_SALT="long_random_value"
npx -y openai-ads-mcp --http

Hosted public mode:

forces readonly mode
refuses to start if OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1
refuses to start if OPENAI_ADS_API_KEY is present
rejects X-OpenAI-Ads-API-Base-Url
allows anonymous initialize and tools/list
requires X-OpenAI-Ads-API-Key for Ads API tool calls
rate-limits discovery and tool calls
logs only redacted summaries, hashes, counts, status, latency, and client metadata

The production runbook is in HOSTED_DEPLOY.md.

Tool Surface

The Python and Node runtimes expose the same 27 tools.

Group	Tools
Account	`get_account`
Campaigns	`list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `set_campaign_state`
AdGroups	`list_ad_groups`, `get_ad_group`, `create_ad_group`, `update_ad_group`, `set_ad_group_state`
Ads	`list_ads`, `get_ad`, `upload_creative`, `create_ad`, `update_ad`, `set_ad_state`
Insights	`get_insights`
Audiences	`list_audiences`, `get_audience`, `search_geo`, `manage_audience`
Conversions	`manage_conversions`, `send_conversions`
Helpers	`build_campaign`, `draft_context_hints`, `bulk_ab_test_hints`

High-use tools

Tool	What it does
`get_account`	Gets the ad account and confirms the API key works.
`get_insights`	Reads account, campaign, ad group, or ad insights with fields, filters, sort, segments, and cursor pagination.
`create_campaign`	Creates a paused campaign with a guarded lifetime budget.
`upload_creative`	Uploads an image URL or local image file and returns `file_id`.
`create_ad`	Creates a paused ad. `chat_card` requires `target_url` and `file_id`.
`build_campaign`	Creates one paused campaign, one paused ad group, and paused ads in a guarded workflow.
`draft_context_hints`	Deterministically drafts API-shaped `context_hints` with no hidden LLM call.
`send_conversions`	Sends conversion events to `https://bzr.openai.com/v1/events?pid=...` after local validation.

Safety Model

This server can affect real ad spend, so the defaults are deliberately cautious.

Create tools default to paused. build_campaign creates every object paused.
Activations are separate tools: set_campaign_state, set_ad_group_state, and set_ad_state.
Budget-setting paths enforce OPENAI_ADS_BUDGET_CEILING_USD, default 100.
To exceed the ceiling, pass confirm_budget=True.
OPENAI_ADS_MCP_READONLY=1 hides every write tool entirely.
Conversion ingest validates at most 1000 events per call, timestamps no older than 7 days, and timestamps no more than 10 minutes in the future.
The server never logs API keys or conversion user data.

MCP annotations are set on every tool. Read tools use readOnlyHint. Write tools use readOnlyHint=false. Activation and budget-changing tools are marked destructive and open-world so hosts can prompt before running them.

Worked Example

First, connect safely:

bash

export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

Ask your assistant:

text

Call get_account and list_campaigns. Confirm the Ads key works and show me what already exists.

Then restart without readonly mode and build a paused campaign:

text

Use draft_context_hints for "AI visibility monitoring software" aimed at growth teams with comparison intent.

Then call build_campaign with:
- name: "AI visibility category test"
- budget_usd: 50
- ad_group: name "Growth teams", billing_event "click", max_bid_usd 1.25, context_hints from the draft
- ads: two chat_card variants using my uploaded file_id

Do not activate anything.

Review the returned campaign, ad group, ads, budget, targeting, and review status. When you are ready to go live, activate each layer explicitly:

text

Call set_campaign_state with state="activate".
Call set_ad_group_state with state="activate".
Call set_ad_state for the approved ad with state="activate".

The Organic Half

Paid placements answer: where did you buy attention?

Trakkr answers: where does your brand show up organically across ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews, Reddit, citations, rankings, competitors, sentiment, prompts, reports, and actions?

Track the organic side at trakkr.ai. Use the Trakkr generator at trakkr.ai/create when you want to turn AI-search gaps into content briefs.

This MCP also exposes one optional resource:

text

openai-ads://trakkr-visibility

It returns a short paste-ready briefing that connects buying ChatGPT ad placements with tracking organic ChatGPT visibility. It is never injected into tool results.

Development

Python:

bash

cd services/openai-ads-mcp/python
python -m pytest -q
python -c "import openai_ads_mcp; print('ok')"

Node:

bash

cd services/openai-ads-mcp/typescript
npm install
npm run build
npm test
OPENAI_ADS_MCP_READONLY=1 node dist/index.js

OpenAPI drift check:

bash

cd services/openai-ads-mcp/typescript
npm run check:openapi

Release Status

This package is beta. Before the first public release, confirm that the PyPI and npm package names openai-ads-mcp are available. See RELEASING.md.

License

MIT, copyright Trakkr.

Install

Configuration

Environment variables

OPENAI_ADS_API_KEYrequiredsecret

OpenAI Ads API key from Ads Manager. Scoped to one ad account.

OPENAI_ADS_MCP_READONLYdefault 1

Set to 1 for first connection so write tools are hidden.

OPENAI_ADS_BUDGET_CEILING_USDdefault 100

Optional budget guard for spend-changing tools. Defaults to 100.

claude_desktop_config.json

{
  "mcpServers": {
    "openai-ads-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "openai-ads-mcp@0.1.6"
      ],
      "env": {
        "OPENAI_ADS_API_KEY": "<YOUR_OPENAI_ADS_API_KEY>",
        "OPENAI_ADS_MCP_READONLY": "1",
        "OPENAI_ADS_BUDGET_CEILING_USD": "100"
      }
    }
  }
}