OpenAI Ads MCP server

openai-ads-mcp

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:

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

Install

Python with uvx:

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

Python with pip:

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

Node with npx:

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

Node with npm:

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

Configuration

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 OPENAIADSMCP_READONLY to enable writes.

Optional environment variables:

Discovery Metadata

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. The hosted endpoint allows anonymous initialize and tools/list; Ads API tool calls require the caller to send X-OpenAI-Ads-API-Key.

MCP client examples

Claude Code, Python runtime

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 Code, Node runtime

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

Cursor or Claude Desktop

Shortened. The full README is on GitHub.