OpenAI Ads Server

An MCP (Model Context Protocol) server that exposes the ChatGPT Ads API (https://api.ads.openai.com/v1) as tools an LLM host can call. Runs as a plain Python process — no cloud platform required.

What it exposes

Tools map to the Advertiser API documented under Ads → API Reference:

Area	Tools
Ad account	get_ad_account
Campaigns	list_campaigns, get_campaign
Ad groups	list_ad_groups, get_ad_group
Ads	list_ads, get_ad
Insights	get_ad_account_insights, get_campaign_insights, get_ad_group_insights, get_ad_insights

Only read/list/report tools are registered (GET-equivalent Ads calls). Mutating actions (create/update/activate/pause/archive/upload) are omitted for now. All exposed tools set read-only hints (readOnlyHint) for MCP clients.

Architecture

python -m openai_ads_mcp          stdio (Cursor, Claude Desktop, etc.)
python -m openai_ads_mcp --transport http   streamable HTTP (remote clients)
  └─ openai_ads_mcp/server.py     registers every tool
       ├─ coordinator.py          FastMCP singleton
       ├─ client.py               httpx wrapper + bearer auth
       └─ tools/                   resource modules

• Single registration point. openai_ads_mcp/server.py imports all tool modules.
• Two transports. Stdio for local IDE hosts; HTTP for remote MCP clients (e.g. via ngrok).

Authentication

• This server → Ads API. Set OPENAI_ADS_API_KEY (header Authorization: Bearer … per the authentication docs).
• Caller → this server. Not enforced by default. Put auth (API gateway, reverse proxy, VPN, etc.) in front of HTTP mode if you expose it publicly.

Secrets: keep Ads keys out of git — copy .env.example to .env and add your key there. Never commit real keys.

Quick start

Prerequisites

• Python 3.11+
• An OpenAI Ads API key

Install

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -r requirements.txt
pip install -e .

Copy the example env file and add your key:

copy .env.example .env
# Edit .env and set OPENAI_ADS_API_KEY

Run (stdio — for Cursor and other IDE MCP hosts)

The process blocks with little or no visible output: MCP uses stdin/stdout for JSON-RPC. You should see a one-line notice on stderr; do not run the server interactively in a normal terminal expecting a prompt.

python -m openai_ads_mcp

Equivalent commands:

openai-ads-mcp
python -m openai_ads_mcp.server

Cursor MCP config — use your venv's python.exe as command, project root as cwd:

{
  "mcpServers": {
    "openai-ads": {
      "command": "C:\\path\\to\\chatgptads-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "openai_ads_mcp"],
      "cwd": "C:\\path\\to\\chatgptads-mcp"
    }
  }
}

Or set OPENAI_ADS_API_KEY in the env block instead of using .env.

Run (HTTP — for remote MCP clients)

python -m openai_ads_mcp --transport http --host 127.0.0.1 --port 8000

Point remote MCP clients at http://127.0.0.1:8000/mcp. To expose publicly, tunnel with ngrok or similar and add auth at the gateway layer.

Environment variables

Variable	Required	Description
OPENAI_ADS_API_KEY	Yes	Ads API key

Project layout

requirements.txt
pyproject.toml
.env.example
openai_ads_mcp/
  __main__.py
  server.py
  coordinator.py
  client.py
  tools/
    ad_account.py
    campaigns.py
    ad_groups.py
    ads.py
    insights.py

See also capabilities.md for a full tool reference.