OpenAI Ads MCP Server

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

openai-ads-mcpis 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.

People often search for this as a ChatGPT Ads MCP because the ads appear in ChatGPT. The package keeps the OpenAI Ads MCP name because ChatGPT Ads are managed through OpenAI Ads, Ads Manager, and the OpenAI Advertiser API.

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

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

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

python -m pip install openai-ads-mcp export OPENAI_ADS_API_KEY="..." export OPENAI_ADS_MCP_READONLY=1 openai-ads-mcp

export OPENAI_ADS_API_KEY="..." export OPENAI_ADS_MCP_READONLY=1 npx -y openai-ads-mcp

npm install -g openai-ads-mcp export OPENAI_ADS_API_KEY="..." export OPENAI_ADS_MCP_READONLY=1 openai-ads-mcp

For local development from this monorepo:

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

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

export OPENAI_ADS_API_KEY="..."

export OPENAI_ADS_MCP_READONLY=1 uvx openai-ads-mcp

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

Readonly mode hides every write tool. They are absent fromtools/listand cannot be called. Once you have confirmed the account and inspected data, unsetOPENAI_ADS_MCP_READONLYto enable writes.

This repo includesserver.jsonfor the official MCP Registry and downstream MCP directories. The canonical registry name is:

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

The Node package includes the matchingmcpName, and the Python package README includes the matchingmcp-namemarker for PyPI ownership verification.

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

That hosted endpoint is for discovery and read-only usage. It does not store or use a Trakkr-owned OpenAI Ads API key. The hosted endpoint allows anonymous initialize andtools/list; Ads API tool calls require the caller to sendX-OpenAI-Ads-API-Key.

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 mcp add openai-ads \ -e OPENAI_ADS_API_KEY=your_ads_key_here \ -e OPENAI_ADS_MCP_READONLY=1 \ -- npx -y openai-ads-mcp

{ "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.

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

Registry-compatible clients should discover this server by name:

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

The registry metadata lists npm, PyPI, and the hosted Streamable HTTP endpoint. The hosted endpoint does not require an API key for discovery, but it does requireX-OpenAI-Ads-API-Keyfor Ads API tool calls.

The repository includes production Dockerfiles for hosted Streamable HTTP deployments:

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 narrowertypescript/Dockerfileis used by the Cloud Run deploy script. For local stdio use, preferuvx openai-ads-mcpornpx -y openai-ads-mcp.

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

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

- URL:http://127.0.0.1:8080/mcplocally, orhttps://your-host/mcpbehind a proxy.
- Health checks:GET /healthz,GET /health, andGET /ready.
- Remote mode forcesOPENAI_ADS_MCP_READONLY=1unlessOPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1is set.
- OPENAI_ADS_MCP_HTTP_TOKENprotects the MCP endpoint withAuthorization: Bearer <token>.
- Clients may sendX-OpenAI-Ads-API-Keyper request, or the server can use a server-sideOPENAI_ADS_API_KEY.

For public hosted endpoints, keep writes disabled and require users to bring their own Ads API key per request. Do not put a shared Ads API key in browser-visible config.

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

- forces readonly mode
- refuses to start ifOPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1
- refuses to start ifOPENAI_ADS_API_KEYis present
- rejectsX-OpenAI-Ads-API-Base-Url
- allows anonymous initialize andtools/list
- requiresX-OpenAI-Ads-API-Keyfor 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 inHOSTED_DEPLOY.md.

The Python and Node runtimes expose the same 27 tools.

get_insightsaccepts the current tagged time-range shape, for example:

{"type":"unix_range","start":1764547200,"end":1765152000}

The older nested shape is normalized for backward compatibility.

For conversion optimization, passbidding_type="conversions"and exactly oneconversion_event_setting_idsvalue tocreate_campaign. The campaign cannot use product-feed mode, and child ad groups must bill by click.build_campaignoffers the same path through its singularconversion_event_setting_idhelper argument. The bid is a CPA input even though OpenAI bills the child ad group per click.

OpenAI's Bulk API remains a limited preview and is not exposed as a general MCP tool. Product-feed campaign objects are supported, but feed connection and catalog upload still happen in Ads Manager or through OpenAI's supported SFTP flow.

This server can affect real ad spend, so the defaults are deliberately cautious.
- Create tools default to paused.build_campaigncreates every object paused.
- Activations are separate tools:set_campaign_state,set_ad_group_state, andset_ad_state.
- Budget-setting paths enforceOPENAI_ADS_BUDGET_CEILING_USD, default100.
- To exceed the ceiling, passconfirm_budget=True.
- OPENAI_ADS_MCP_READONLY=1hides 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.
- Usevalidate_only=trueto validate a conversion batch without ingesting it.
- The server never logs API keys or conversion user data.

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

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

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:

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:

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".

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 attrakkr.ai. Use the Trakkr generator attrakkr.ai/createwhen you want to turn AI-search gaps into content briefs.

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

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

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

A shared campaign canvas for you and your AI agent: briefed by your brand rules, gated by your approval.