OpenAI Ads MCP

openai-ads-mcp

Trakkr は、オーガニックと有料の両方で、AI 可視性のファネル全体を追跡します。これは、有料側を補完するオープンソースのパッケージです。

openai-ads-mcp は、OpenAI Ads、ChatGPT Ads、および OpenAI の Advertiser API 向けの、型定義された Model Context Protocol サーバーです。Claude、Cursor、Codex、VS Code などの MCP クライアントから、Ads アカウントの確認、パフォーマンスインサイトの取得、一時停止状態のキャンペーンの作成、クリエイティブのアップロード、オーディエンスの管理、コンバージョンイベントの送信ができます。

広告が ChatGPT に表示されることから、ChatGPT Ads MCP として検索されることもよくあります。このパッケージでは、ChatGPT Ads は OpenAI Ads、Ads Manager、および OpenAI Advertiser API を通じて管理されるため、OpenAI Ads MCP という名称を使用しています。

現在の公開リリース：0.1.7。

同じツール名、引数、デフォルト値、安全モデル、およびベンダー提供の OpenAPI リファレンスを備えた、2 種類のランタイムで提供されています。

ランタイム	推奨インストール方法	パッケージパス
Python	uvx openai-ads-mcp	python/
Node	npx -y openai-ads-mcp	typescript/

目的はシンプルです。誤って支出が発生しやすくならないようにしながら、AI アシスタントから OpenAI Ads を使えるようにすることです。

インストール

Python（uvx を使用）：

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

Python（pip を使用）：

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

Node（npx を使用）：

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

Node（npm を使用）：

npm install -g openai-ads-mcp
export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
openai-ads-mcp

このモノレポからローカル開発する場合：

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

設定

OpenAI Ads Manager で Ads API キーを作成し、環境変数として渡します。

export OPENAI_ADS_API_KEY="..."

最初の接続時に推奨する設定：

export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

または Node の場合：

export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp

読み取り専用モードでは、すべての書き込みツールが非表示になります。これらのツールは tools/list に含まれず、呼び出すこともできません。アカウントを確認し、データを調べた後、OPENAI_ADS_MCP_READONLY の設定を解除すると、書き込みが有効になります。

任意の環境変数：

変数	用途
OPENAI_ADS_API_KEY	https://api.ads.openai.com/v1 用の必須ベアラーキーです。
OPENAI_ADS_API_BASE_URL	テストまたはプロキシ向けの任意の HTTPS オーバーライドです。
OPENAI_ADS_MCP_READONLY	1 または true に設定すると、読み取りツールのみが登録されます。
OPENAI_ADS_BUDGET_CEILING_USD	任意の予算ガードです。デフォルトは 100 です。

検出メタデータ

このリポジトリには、公式 MCP Registry および下流の MCP ディレクトリ向けの server.json が含まれています。正式なレジストリ名は次のとおりです。

io.github.trakkr-aisearch/openai-ads-mcp

Node パッケージには一致する mcpName が含まれ、Python パッケージの README には、PyPI の所有権確認に必要な一致する mcp-name マーカーが含まれています。

レジストリのメタデータには、ホスト型の読み取り専用 Streamable HTTP エンドポイントも記載されています。

https://openai-ads-mcp.trakkr.ai/mcp

このホスト型エンドポイントは、検出と読み取り専用での使用を目的としています。Trakkr が所有する OpenAI Ads API キーを保存したり使用したりすることはありません。 ホスト型エンドポイントでは、匿名での initialize と tools/list が可能です。Ads API のツール呼び出しには、呼び出し元が X-OpenAI-Ads-API-Key を送信する必要があります。

MCP クライアントの例

Claude Code、Python ランタイム

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 ランタイム

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 または Claude Desktop

{
  "mcpServers": {
    "openai-ads": {
      "command": "uvx",
      "args": ["openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your_ads_key_here",
        "OPENAI_ADS_MCP_READONLY": "1"
      }
    }
  }
}

Node ランタイムでは、"command": "npx" および "args": ["-y", "openai-ads-mcp"] を使用します。

Codex CLI

[mcp_servers.openai_ads]
command = "uvx"
args = ["openai-ads-mcp"]
env = { OPENAI_ADS_API_KEY = "your_ads_key_here", OPENAI_ADS_MCP_READONLY = "1" }

MCP Registry

レジストリ互換のクライアントは、次の名前でこのサーバーを検出できます。

io.github.trakkr-aisearch/openai-ads-mcp

レジストリのメタデータには、npm、PyPI、およびホスト型の Streamable HTTP エンドポイントが記載されています。検出に API キーは必要ありませんが、Ads API のツール呼び出しには X-OpenAI-Ads-API-Key が必要です。

Docker

このリポジトリには、ホスト型の Streamable HTTP デプロイメント向けに、本番環境用の Dockerfile が含まれています。

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

より対象を絞った typescript/Dockerfile は、Cloud Run のデプロイスクリプトで使用されます。ローカルの stdio で使用する場合は、uvx openai-ads-mcp または npx -y openai-ads-mcp を推奨します。

Streamable HTTP

Node ランタイムでは、ホスト型またはチームでのデプロイメント向けに、Streamable HTTP 経由で MCP を提供することもできます。

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

デフォルト：

• URL：ローカルでは http://127.0.0.1:8080/mcp、プロキシ経由では https://your-host/mcp。
• ヘルスチェック：GET /healthz、GET /health、GET /ready。
• リモートモードでは、OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1 が設定されていない限り、OPENAI_ADS_MCP_READONLY=1 が強制されます。
• OPENAI_ADS_MCP_HTTP_TOKEN を設定すると、Authorization: Bearer <token> で MCP エンドポイントを保護できます。
• クライアントはリクエストごとに X-OpenAI-Ads-API-Key を送信できます。または、サーバー側で OPENAI_ADS_API_KEY を使用できます。

ホスト環境で便利な環境変数：

変数	用途
PORT または OPENAI_ADS_MCP_HTTP_PORT	HTTP ポート。デフォルトは 8080 です。
OPENAI_ADS_MCP_HTTP_PATH	MCP パス。デフォルトは /mcp です。
OPENAI_ADS_MCP_HEALTH_PATH	ヘルスチェックパス。デフォルトは /healthz です。
OPENAI_ADS_MCP_HTTP_TOKEN	ホスト型クライアントに必要な任意のベアラートークンです。
OPENAI_ADS_MCP_HTTP_ALLOW_WRITES	HTTP 経由で書き込みツールを公開する場合に限り、1 に設定します。
OPENAI_ADS_MCP_HTTP_CORS_ORIGIN	任意の CORS オリジンです。デフォルトは * です。

一般公開のホスト型エンドポイントでは、書き込みを無効にし、ユーザーがリクエストごとに独自の Ads API キーを持ち込むことを必須にしてください。ブラウザーから見える設定に共有の Ads API キーを含めないでください。

一般公開ホスト型モード

一般公開の検出エンドポイントには、次を使用します。

export OPENAI_ADS_MCP_HOSTED_PUBLIC=1
export OPENAI_ADS_MCP_TELEMETRY_SALT="long_random_value"
npx -y openai-ads-mcp --http

一般公開ホスト型モードでは：

• 読み取り専用モードが強制されます
• OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1 が設定されている場合、起動を拒否します
• OPENAI_ADS_API_KEY が設定されている場合、起動を拒否します
• X-OpenAI-Ads-API-Base-Url を拒否します
• 匿名での initialize と tools/list を許可します
• Ads API ツールの呼び出しには X-OpenAI-Ads-API-Key が必要です
• 検出とツールの呼び出しをレート制限します
• マスキングされた概要、ハッシュ、件数、ステータス、レイテンシー、クライアントメタデータのみをログに記録します

本番環境の運用手順書は HOSTED_DEPLOY.md にあります。

ツール一覧

Python ランタイムと Node ランタイムでは、同じ 27 個のツールを利用できます。

グループ	ツール
アカウント	get_account
キャンペーン	list_campaigns、get_campaign、create_campaign、update_campaign、set_campaign_state
広告グループ	list_ad_groups、get_ad_group、create_ad_group、update_ad_group、set_ad_group_state
広告	list_ads、get_ad、upload_creative、create_ad、update_ad、set_ad_state
インサイト	get_insights
オーディエンス	list_audiences、get_audience、search_geo、manage_audience
コンバージョン	manage_conversions、send_conversions
ヘルパー	build_campaign、draft_context_hints、bulk_ab_test_hints

使用頻度の高いツール

ツール	機能
get_account	広告アカウントを取得し、API キーが機能することを確認します。
get_insights	フィールド、フィルター、並べ替え、セグメント、カーソルページネーションを指定して、アカウント、キャンペーン、広告グループ、または広告のインサイトを読み取ります。
create_campaign	一時停止状態のキャンペーンを、上限を設けたライフタイム予算で作成します。単一のイベント設定を使うコンバージョン最適化キャンペーンも作成できます。
upload_creative	画像 URL またはローカルの画像ファイルをアップロードし、file_id を返します。
create_ad	一時停止状態の広告を作成します。chat_card には target_url と file_id が必要です。
build_campaign	上限を設けたワークフローで、一時停止状態のキャンペーンを 1 件、広告グループを 1 件、広告を複数作成します。
draft_context_hints	非公開の LLM 呼び出しを行わず、API 形式の context_hints を決定論的に下書きします。
send_conversions	ローカルでの検証後、https://bzr.openai.com/v1/events?pid=... にコンバージョンイベントを送信します。validate_only を任意で指定できます。obref とモバイルアプリのライフサイクルイベントに対応しています。

get_insights は、次のような現在のタグ付き時間範囲形式を受け付けます。

{"type":"unix_range","start":1764547200,"end":1765152000}

古いネスト形式は、後方互換性のために正規化されます。

コンバージョン最適化では、create_campaign に bidding_type="conversions" と、値を 1 つだけ持つ conversion_event_setting_ids を渡してください。このキャンペーンでは商品フィードモードを使用できず、子広告グループはクリック課金にする必要があります。build_campaign でも、単一の conversion_event_setting_id ヘルパー引数を使って同じ方法を利用できます。OpenAI は子広告グループにクリック課金しますが、入札額は CPA の値です。

OpenAI の Bulk API は引き続き限定プレビューであり、汎用 MCP ツールとしては公開されていません。商品フィードのキャンペーンオブジェクトには対応していますが、フィードの接続とカタログのアップロードは、引き続き Ads Manager または OpenAI がサポートする SFTP フローで行う必要があります。

安全性モデル

このサーバーは実際の広告費に影響を与える可能性があるため、デフォルト設定は意図的に慎重にしています。

1. 作成ツールはデフォルトで一時停止状態にします。build_campaign ではすべてのオブジェクトが一時停止状態で作成されます。
2. 有効化には、set_campaign_state、set_ad_group_state、set_ad_state の個別ツールを使います。
3. 予算を設定する経路では、デフォルト値が 100 の OPENAI_ADS_BUDGET_CEILING_USD を上限として適用します。
4. 上限を超える場合は、confirm_budget=True を渡してください。
5. OPENAI_ADS_MCP_READONLY=1 を設定すると、すべての書き込みツールが非表示になります。
6. コンバージョンの取り込みでは、1 回の呼び出しにつき最大 1000 件のイベント、7 日以内のタイムスタンプ、現在より 10 分を超えて先ではないタイムスタンプを検証します。
7. コンバージョンのバッチを取り込まずに検証するには、validate_only=true を使用してください。
8. このサーバーは API キーやコンバージョンのユーザーデータをログに記録しません。

MCP のアノテーションはすべてのツールに設定されています。読み取りツールには readOnlyHint を使用します。書き込みツールには readOnlyHint=false を使用します。有効化や予算変更を行うツールには破壊的かつオープンワールドのマークを付けており、ホストが実行前に確認を求められるようになっています。

使用例

まず、安全に接続します。

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

アシスタントに次のように依頼します。

Call get_account and list_campaigns. Confirm the Ads key works and show me what already exists.

次に、読み取り専用モードを解除して再起動し、一時停止状態のキャンペーンを作成します。

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.

返されたキャンペーン、広告グループ、広告、予算、ターゲティング、審査ステータスを確認します。公開する準備ができたら、各レイヤーを明示的に有効化します。

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".

オーガニック側

有料掲載でわかるのは、どこで注目を集めるために費用をかけたかです。

Trakkr でわかるのは、ChatGPT、Perplexity、Gemini、Claude、Google AI Overviews、Reddit におけるブランドのオーガニックな表示状況、引用、ランキング、競合他社、センチメント、プロンプト、レポート、アクションです。

trakkr.ai でオーガニック側を追跡しましょう。AI 検索のギャップをコンテンツ概要に変換するには、trakkr.ai/create の Trakkr ジェネレーターをご利用ください。

この MCP では、オプションのリソースも 1 つ公開しています。

openai-ads://trakkr-visibility

これは、ChatGPT 広告枠の購入と、ChatGPT におけるオーガニックな可視性の追跡を結び付ける、すぐに貼り付けられる簡潔なブリーフィングを返します。ツールの結果に自動で挿入されることはありません。

開発

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 の差分チェック：

cd services/openai-ads-mcp/typescript
npm run check:openapi
npm run check:docs

スケジュールされたワークフローでは、両方のチェックを毎週実行します。OpenAPI の比較では、スキーマの差分を検出します。ガイドのチェックでは、ダウンロード可能なスキーマ以外で説明されている現在の動作を確認します。これには、タグ付きのインサイト範囲、obref、モバイルアプリのイベント、コンバージョンの最適化、広告主の準備状況、チャットカードに必須の画像、プレビューが限定されている Bulk API が含まれます。

リリース状況

0.1.7 は、npm、PyPI、ホストされたエンドポイント、および公開中の MCP Registry エントリーにおける現在のパブリックベータリリースです。レジストリのメタデータのバージョンは変更できないため、このリポジトリでのレジストリのみの修正は、次のパッケージリリースバージョンと合わせてリリースしてください。リリース作業は、公開前に専用のパブリックリポジトリと同期します。詳細は RELEASING.md をご覧ください。

ライセンス

MIT、著作権者は Trakkr です。