openai-ads-mcp

openai-ads-mcp for Node

Node runtime for openai-ads-mcp, a typed MCP server for OpenAI Ads, ChatGPT Ads MCP workflows, and OpenAI's Advertiser API.

It exposes the same tools, arguments, defaults, readonly mode, and budget guard as the Python package.

Quickstart

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

Readonly mode hides every write tool from tools/list. Unset OPENAI_ADS_MCP_READONLY only after you have confirmed the account and reviewed existing campaigns.

Local Development

npm install
npm run build
npm test
OPENAI_ADS_MCP_READONLY=1 node dist/index.js

Streamable HTTP

For hosted or team deployments, start the Node runtime with Streamable HTTP:

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

The MCP endpoint is /mcp; health checks are available at /healthz, /health, and /ready. Remote mode is read-only by default. Set OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1 only when write tools should be visible over HTTP. Clients can pass X-OpenAI-Ads-API-Key per request, or the server can use a server-side OPENAI_ADS_API_KEY.

For public hosted endpoints, use OPENAI_ADS_MCP_HOSTED_PUBLIC=1. Hosted public mode forces readonly mode, rejects server-side OPENAI_ADS_API_KEY, blocks X-OpenAI-Ads-API-Base-Url, requires OPENAI_ADS_MCP_TELEMETRY_SALT, exposes /.well-known/mcp/server-card.json, and logs only redacted summaries.

Environment

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.
OPENAI_ADS_MCP_HTTP_TOKEN	Optional bearer token for hosted HTTP mode.
OPENAI_ADS_MCP_HTTP_ALLOW_WRITES	Set to 1 to expose write tools in HTTP mode.
OPENAI_ADS_MCP_HOSTED_PUBLIC	Set to 1 for the public read-only hosted endpoint safety profile.
OPENAI_ADS_MCP_TELEMETRY_SALT	Required in hosted public mode for IP, API-key, and text hashes.
OPENAI_ADS_MCP_HOSTED_DISABLED	Set to 1 to make /mcp return 503 while /healthz remains available.
OPENAI_ADS_MCP_EDGE_SECRET	Optional shared secret expected in X-Trakkr-Edge-Secret when a Worker is in front.

Full docs live in the repository root README.