The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the OpenAI Ads MCP listing page.
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.
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.
Current public release: 0.1.7.
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.
Python with uvx:
Python with pip:
Node with npx:
Node with npm:
For local development from this monorepo:
Create an Ads API key in OpenAI Ads Manager, then pass it as an environment variable.
Recommended first connection:
Or with Node:
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. |
This repo includes server.json for the official MCP Registry and downstream MCP directories. The canonical registry name is:
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:
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 and tools/list; Ads API tool calls require the caller to send X-OpenAI-Ads-API-Key.
Use "command": "npx" and "args": ["-y", "openai-ads-mcp"] for the Node runtime.
Registry-compatible clients should discover this server by name:
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 require X-OpenAI-Ads-API-Key for Ads API tool calls.
The repository includes production Dockerfiles for hosted Streamable HTTP deployments:
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.
The Node runtime can also serve MCP over Streamable HTTP for hosted or team deployments:
Defaults:
http://127.0.0.1:8080/mcp locally, or https://your-host/mcp behind a proxy.GET /healthz, GET /health, and GET /ready.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>.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 and require users to bring their own Ads API key per request. Do not put a shared Ads API key in browser-visible config.
For a public discovery endpoint, use:
Hosted public mode:
OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1OPENAI_ADS_API_KEY is presentX-OpenAI-Ads-API-Base-Urltools/listX-OpenAI-Ads-API-Key for Ads API tool callsThe production runbook is in HOSTED_DEPLOY.md.
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 |
| 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, including conversion-optimized campaigns with one event setting. |
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, with optional validate_only. Supports obref and mobile app lifecycle events. |
get_insights accepts the current tagged time-range shape, for example:
The older nested shape is normalized for backward compatibility.
For conversion optimization, pass bidding_type="conversions" and exactly one
conversion_event_setting_ids value to create_campaign. The campaign cannot
use product-feed mode, and child ad groups must bill by click. build_campaign
offers the same path through its singular conversion_event_setting_id helper
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.
build_campaign creates every object paused.set_campaign_state, set_ad_group_state, and set_ad_state.OPENAI_ADS_BUDGET_CEILING_USD, default 100.confirm_budget=True.OPENAI_ADS_MCP_READONLY=1 hides every write tool entirely.validate_only=true to validate a conversion batch without ingesting it.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.
First, connect safely:
Ask your assistant:
Then restart without readonly mode and build a paused campaign:
Review the returned campaign, ad group, ads, budget, targeting, and review status. When you are ready to go live, activate each layer explicitly:
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:
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.
Python:
Node:
OpenAPI drift check:
The scheduled workflow runs both checks weekly. The OpenAPI comparison catches
schema drift. The guide check covers current behavior documented outside the
downloadable schema, including tagged insight ranges, obref, mobile app
events, conversion optimization, advertiser readiness, required chat-card
images, and the limited-preview Bulk API.
0.1.7 is the current public beta release for npm, PyPI, the hosted endpoint, and the live MCP Registry entry. Registry metadata versions are immutable, so registry-only corrections in this repo should ship with the next package release version. Release work is synced to the dedicated public repository before publishing. See RELEASING.md.
MIT, copyright Trakkr.