Server data from the Official MCP Registry
OpenAI and ChatGPT Ads tools for campaigns, creatives, audiences, and insights.
OpenAI and ChatGPT Ads tools for campaigns, creatives, audiences, and insights.
Valid MCP server (2 strong, 2 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
9 files analyzed · 2 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: OPENAI_ADS_API_KEY
Environment variable: OPENAI_ADS_MCP_READONLY
Environment variable: OPENAI_ADS_BUDGET_CEILING_USD
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-trakkr-aisearch-openai-ads-mcp": {
"env": {
"OPENAI_ADS_API_KEY": "your-openai-ads-api-key-here",
"OPENAI_ADS_MCP_READONLY": "your-openai-ads-mcp-readonly-here",
"OPENAI_ADS_BUDGET_CEILING_USD": "your-openai-ads-budget-ceiling-usd-here"
},
"args": [
"-y",
"openai-ads-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
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.
Python with uvx:
uvx openai-ads-mcp
Python with pip:
python -m pip install openai-ads-mcp
openai-ads-mcp
Node with npx:
npx -y openai-ads-mcp
Node with npm:
npm install -g openai-ads-mcp
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="..."
Recommended first connection:
export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp
Or with Node:
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. |
This repo includes server.json for 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 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:
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.
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" }
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 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:
export OPENAI_ADS_MCP_HTTP_TOKEN="choose_a_long_random_token"
npx -y openai-ads-mcp --http
Defaults:
http://127.0.0.1:8080/mcp locally, or https://your-host/mcp behind a proxy.GET /healthz.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 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.
For a public discovery endpoint, use:
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:
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. |
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. |
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.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:
export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp
Ask your assistant:
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 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:
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.
Python:
cd services/openai-ads-mcp/python
python -m pytest -q
python -c "import openai_ads_mcp; print('ok')"
Node:
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:
cd services/openai-ads-mcp/typescript
npm run check:openapi
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.
MIT, copyright Trakkr.
Be the first to review this server!
by Modelcontextprotocol · AI & ML
Dynamic and reflective problem-solving through structured thought sequences
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.