{
  "markdown": "# openai-ads-mcp\n\nTrakkr tracks the full AI-visibility funnel, organic and paid. This is the open-source paid-side companion.\n\n`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.\n\nPeople 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.\n\nCurrent public release: `0.1.7`.\n\nIt ships in two runtimes with the same tool names, arguments, defaults, safety model, and vendored OpenAPI reference:\n\n| Runtime | Best install | Package path |\n| --- | --- | --- |\n| Python | `uvx openai-ads-mcp` | `python/` |\n| Node | `npx -y openai-ads-mcp` | `typescript/` |\n\nThe goal is simple: make OpenAI Ads workable from an AI assistant without making spend easy to trigger by accident.\n\n## Install\n\nPython with `uvx`:\n\n```bash\nexport OPENAI_ADS_API_KEY=\"...\"\nexport OPENAI_ADS_MCP_READONLY=1\nuvx openai-ads-mcp\n```\n\nPython with pip:\n\n```bash\npython -m pip install openai-ads-mcp\nexport OPENAI_ADS_API_KEY=\"...\"\nexport OPENAI_ADS_MCP_READONLY=1\nopenai-ads-mcp\n```\n\nNode with `npx`:\n\n```bash\nexport OPENAI_ADS_API_KEY=\"...\"\nexport OPENAI_ADS_MCP_READONLY=1\nnpx -y openai-ads-mcp\n```\n\nNode with npm:\n\n```bash\nnpm install -g openai-ads-mcp\nexport OPENAI_ADS_API_KEY=\"...\"\nexport OPENAI_ADS_MCP_READONLY=1\nopenai-ads-mcp\n```\n\nFor local development from this monorepo:\n\n```bash\ncd services/openai-ads-mcp/python\npython -m pip install -e .\npython -m openai_ads_mcp\n\ncd ../typescript\nnpm install\nnpm run build\nnode dist/index.js\n```\n\n## Configuration\n\nCreate an Ads API key in OpenAI Ads Manager, then pass it as an environment variable.\n\n```bash\nexport OPENAI_ADS_API_KEY=\"...\"\n```\n\nRecommended first connection:\n\n```bash\nexport OPENAI_ADS_MCP_READONLY=1\nuvx openai-ads-mcp\n```\n\nOr with Node:\n\n```bash\nexport OPENAI_ADS_MCP_READONLY=1\nnpx -y openai-ads-mcp\n```\n\nReadonly 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.\n\nOptional environment variables:\n\n| Variable | Purpose |\n| --- | --- |\n| `OPENAI_ADS_API_KEY` | Required bearer key for `https://api.ads.openai.com/v1`. |\n| `OPENAI_ADS_API_BASE_URL` | Optional HTTPS override for tests or proxies. |\n| `OPENAI_ADS_MCP_READONLY` | Set to `1` or `true` to register read tools only. |\n| `OPENAI_ADS_BUDGET_CEILING_USD` | Optional budget guard. Default `100`. |\n\n## Discovery Metadata\n\nThis repo includes `server.json` for the official MCP Registry and downstream MCP directories. The canonical registry name is:\n\n```text\nio.github.trakkr-aisearch/openai-ads-mcp\n```\n\nThe Node package includes the matching `mcpName`, and the Python package README includes the matching `mcp-name` marker for PyPI ownership verification.\n\nThe registry metadata also advertises the hosted read-only Streamable HTTP endpoint:\n\n```text\nhttps://openai-ads-mcp.trakkr.ai/mcp\n```\n\nThat hosted endpoint is for discovery and read-only usage. It does not store or use a Trakkr-owned OpenAI Ads API key.\nThe hosted endpoint allows anonymous initialize and `tools/list`; Ads API tool calls require the caller to send `X-OpenAI-Ads-API-Key`.\n\n## MCP client examples\n\n### Claude Code, Python runtime\n\n```bash\nclaude mcp add openai-ads \\\n  -e OPENAI_ADS_API_KEY=your_ads_key_here \\\n  -e OPENAI_ADS_MCP_READONLY=1 \\\n  -- uvx openai-ads-mcp\n```\n\n### Claude Code, Node runtime\n\n```bash\nclaude mcp add openai-ads \\\n  -e OPENAI_ADS_API_KEY=your_ads_key_here \\\n  -e OPENAI_ADS_MCP_READONLY=1 \\\n  -- npx -y openai-ads-mcp\n```\n\n### Cursor or Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"openai-ads\": {\n      \"command\": \"uvx\",\n      \"args\": [\"openai-ads-mcp\"],\n      \"env\": {\n        \"OPENAI_ADS_API_KEY\": \"your_ads_key_here\",\n        \"OPENAI_ADS_MCP_READONLY\": \"1\"\n      }\n    }\n  }\n}\n```\n\nUse `\"command\": \"npx\"` and `\"args\": [\"-y\", \"openai-ads-mcp\"]` for the Node runtime.\n\n### Codex CLI\n\n```toml\n[mcp_servers.openai_ads]\ncommand = \"uvx\"\nargs = [\"openai-ads-mcp\"]\nenv = { OPENAI_ADS_API_KEY = \"your_ads_key_here\", OPENAI_ADS_MCP_READONLY = \"1\" }\n```\n\n### MCP Registry\n\nRegistry-compatible clients should discover this server by name:\n\n```text\nio.github.trakkr-aisearch/openai-ads-mcp\n```\n\nThe 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.\n\n### Docker\n\nThe repository includes production Dockerfiles for hosted Streamable HTTP deployments:\n\n```bash\ndocker build -t openai-ads-mcp .\ndocker run --rm -p 8080:8080 \\\n  -e OPENAI_ADS_MCP_HOSTED_PUBLIC=1 \\\n  -e OPENAI_ADS_MCP_TELEMETRY_SALT=\"local-test-salt\" \\\n  openai-ads-mcp\n```\n\nThe 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`.\n\n## Streamable HTTP\n\nThe Node runtime can also serve MCP over Streamable HTTP for hosted or team deployments:\n\n```bash\nexport OPENAI_ADS_MCP_HTTP_TOKEN=\"choose_a_long_random_token\"\nexport OPENAI_ADS_MCP_READONLY=1\nnpx -y openai-ads-mcp --http\n```\n\nDefaults:\n\n- URL: `http://127.0.0.1:8080/mcp` locally, or `https://your-host/mcp` behind a proxy.\n- Health checks: `GET /healthz`, `GET /health`, and `GET /ready`.\n- Remote mode forces `OPENAI_ADS_MCP_READONLY=1` unless `OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1` is set.\n- `OPENAI_ADS_MCP_HTTP_TOKEN` protects the MCP endpoint with `Authorization: Bearer <token>`.\n- Clients may send `X-OpenAI-Ads-API-Key` per request, or the server can use a server-side `OPENAI_ADS_API_KEY`.\n\nUseful hosted env vars:\n\n| Variable | Purpose |\n| --- | --- |\n| `PORT` or `OPENAI_ADS_MCP_HTTP_PORT` | HTTP port. Default `8080`. |\n| `OPENAI_ADS_MCP_HTTP_PATH` | MCP path. Default `/mcp`. |\n| `OPENAI_ADS_MCP_HEALTH_PATH` | Health path. Default `/healthz`. |\n| `OPENAI_ADS_MCP_HTTP_TOKEN` | Optional bearer token required by hosted clients. |\n| `OPENAI_ADS_MCP_HTTP_ALLOW_WRITES` | Set to `1` only when you want write tools exposed over HTTP. |\n| `OPENAI_ADS_MCP_HTTP_CORS_ORIGIN` | Optional CORS origin. Default `*`. |\n\nFor 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.\n\n### Public hosted mode\n\nFor a public discovery endpoint, use:\n\n```bash\nexport OPENAI_ADS_MCP_HOSTED_PUBLIC=1\nexport OPENAI_ADS_MCP_TELEMETRY_SALT=\"long_random_value\"\nnpx -y openai-ads-mcp --http\n```\n\nHosted public mode:\n\n- forces readonly mode\n- refuses to start if `OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1`\n- refuses to start if `OPENAI_ADS_API_KEY` is present\n- rejects `X-OpenAI-Ads-API-Base-Url`\n- allows anonymous initialize and `tools/list`\n- requires `X-OpenAI-Ads-API-Key` for Ads API tool calls\n- rate-limits discovery and tool calls\n- logs only redacted summaries, hashes, counts, status, latency, and client metadata\n\nThe production runbook is in `HOSTED_DEPLOY.md`.\n\n## Tool Surface\n\nThe Python and Node runtimes expose the same 27 tools.\n\n| Group | Tools |\n| --- | --- |\n| Account | `get_account` |\n| Campaigns | `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `set_campaign_state` |\n| AdGroups | `list_ad_groups`, `get_ad_group`, `create_ad_group`, `update_ad_group`, `set_ad_group_state` |\n| Ads | `list_ads`, `get_ad`, `upload_creative`, `create_ad`, `update_ad`, `set_ad_state` |\n| Insights | `get_insights` |\n| Audiences | `list_audiences`, `get_audience`, `search_geo`, `manage_audience` |\n| Conversions | `manage_conversions`, `send_conversions` |\n| Helpers | `build_campaign`, `draft_context_hints`, `bulk_ab_test_hints` |\n\n### High-use tools\n\n| Tool | What it does |\n| --- | --- |\n| `get_account` | Gets the ad account and confirms the API key works. |\n| `get_insights` | Reads account, campaign, ad group, or ad insights with fields, filters, sort, segments, and cursor pagination. |\n| `create_campaign` | Creates a paused campaign with a guarded lifetime budget, including conversion-optimized campaigns with one event setting. |\n| `upload_creative` | Uploads an image URL or local image file and returns `file_id`. |\n| `create_ad` | Creates a paused ad. `chat_card` requires `target_url` and `file_id`. |\n| `build_campaign` | Creates one paused campaign, one paused ad group, and paused ads in a guarded workflow. |\n| `draft_context_hints` | Deterministically drafts API-shaped `context_hints` with no hidden LLM call. |\n| `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. |\n\n`get_insights` accepts the current tagged time-range shape, for example:\n\n```json\n{\"type\":\"unix_range\",\"start\":1764547200,\"end\":1765152000}\n```\n\nThe older nested shape is normalized for backward compatibility.\n\nFor conversion optimization, pass `bidding_type=\"conversions\"` and exactly one\n`conversion_event_setting_ids` value to `create_campaign`. The campaign cannot\nuse product-feed mode, and child ad groups must bill by click. `build_campaign`\noffers the same path through its singular `conversion_event_setting_id` helper\nargument. The bid is a CPA input even though OpenAI bills the child ad group per\nclick.\n\nOpenAI's Bulk API remains a limited preview and is not exposed as a general MCP\ntool. Product-feed campaign objects are supported, but feed connection and\ncatalog upload still happen in Ads Manager or through OpenAI's supported SFTP\nflow.\n\n## Safety Model\n\nThis server can affect real ad spend, so the defaults are deliberately cautious.\n\n1. Create tools default to paused. `build_campaign` creates every object paused.\n2. Activations are separate tools: `set_campaign_state`, `set_ad_group_state`, and `set_ad_state`.\n3. Budget-setting paths enforce `OPENAI_ADS_BUDGET_CEILING_USD`, default `100`.\n4. To exceed the ceiling, pass `confirm_budget=True`.\n5. `OPENAI_ADS_MCP_READONLY=1` hides every write tool entirely.\n6. 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.\n7. Use `validate_only=true` to validate a conversion batch without ingesting it.\n8. The server never logs API keys or conversion user data.\n\nMCP 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.\n\n## Worked Example\n\nFirst, connect safely:\n\n```bash\nexport OPENAI_ADS_API_KEY=\"...\"\nexport OPENAI_ADS_MCP_READONLY=1\nuvx openai-ads-mcp\n```\n\nAsk your assistant:\n\n```text\nCall get_account and list_campaigns. Confirm the Ads key works and show me what already exists.\n```\n\nThen restart without readonly mode and build a paused campaign:\n\n```text\nUse draft_context_hints for \"AI visibility monitoring software\" aimed at growth teams with comparison intent.\n\nThen call build_campaign with:\n- name: \"AI visibility category test\"\n- budget_usd: 50\n- ad_group: name \"Growth teams\", billing_event \"click\", max_bid_usd 1.25, context_hints from the draft\n- ads: two chat_card variants using my uploaded file_id\n\nDo not activate anything.\n```\n\nReview the returned campaign, ad group, ads, budget, targeting, and review status. When you are ready to go live, activate each layer explicitly:\n\n```text\nCall set_campaign_state with state=\"activate\".\nCall set_ad_group_state with state=\"activate\".\nCall set_ad_state for the approved ad with state=\"activate\".\n```\n\n## The Organic Half\n\nPaid placements answer: where did you buy attention?\n\nTrakkr 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?\n\nTrack the organic side at [trakkr.ai](https://trakkr.ai). Use the Trakkr generator at [trakkr.ai/create](https://trakkr.ai/create) when you want to turn AI-search gaps into content briefs.\n\nThis MCP also exposes one optional resource:\n\n```text\nopenai-ads://trakkr-visibility\n```\n\nIt returns a short paste-ready briefing that connects buying ChatGPT ad placements with tracking organic ChatGPT visibility. It is never injected into tool results.\n\n## Development\n\nPython:\n\n```bash\ncd services/openai-ads-mcp/python\npython -m pytest -q\npython -c \"import openai_ads_mcp; print('ok')\"\n```\n\nNode:\n\n```bash\ncd services/openai-ads-mcp/typescript\nnpm install\nnpm run build\nnpm test\nOPENAI_ADS_MCP_READONLY=1 node dist/index.js\n```\n\nOpenAPI drift check:\n\n```bash\ncd services/openai-ads-mcp/typescript\nnpm run check:openapi\nnpm run check:docs\n```\n\nThe scheduled workflow runs both checks weekly. The OpenAPI comparison catches\nschema drift. The guide check covers current behavior documented outside the\ndownloadable schema, including tagged insight ranges, `obref`, mobile app\nevents, conversion optimization, advertiser readiness, required chat-card\nimages, and the limited-preview Bulk API.\n\n## Release Status\n\n`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`.\n\n## License\n\nMIT, copyright Trakkr.\n",
  "bytes": 13741,
  "sha": "e34d3e88240f953cf9dfb11cc9a5b29b8bd8b88603455597cb9f00b6b0f4c3e8",
  "repo_slug": "trakkr-aisearch/openai-ads-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_trakkr_aisearch_openai_ads_mcp_b48e50c7/readme"
}