Hypd Ai Openai Ads

openai-ads-mcp

OpenAI Ads（Advertiser）API 向けの Model Context Protocol（MCP） サーバーです。MCP 対応クライアントである Claude Desktop、Cursor、VS Code などから、自然言語で OpenAI Ads のキャンペーン、広告グループ、広告、パフォーマンスのインサイトを確認できます。

読み取り専用です。 この初回リリースではデータの読み取りのみを行います。作成、編集、一時停止は一切行わず、予算を消費することもありません。書き込み操作はロードマップに記載されています。

非公式です。 これはコミュニティプロジェクトであり、OpenAI との提携や承認を受けていません。免責事項をご覧ください。

---

概要

OpenAI Ads API では、広告主のアカウント、キャンペーン、広告グループ、広告、レポートを利用できます。このサーバーは、API の読み取りエンドポイントを MCP ツールとしてラップするため、AI アシスタントは次のような質問に回答できます。

• 「OpenAI Ads API キーは機能していますか？　どのアカウントに紐づいていますか？」
• 「有効なキャンペーンとその予算を一覧表示してください。」
• 「過去 30 日間のキャンペーン cmp_123 の費用、クリック数、CTR を日別に表示してください。」
• 「広告グループ adg_456 で、審査待ちの広告はどれですか？」

特長

• アカウント、キャンペーン、広告グループ、広告、各階層のインサイトを網羅する読み取り専用ツール 11 種類。
• API の JSON をそのまま返すため、翻訳によって情報が失われることはありません。
• 明確なエラー表示 — HTTP ステータスと API エラー本文をモデルに提示し、握りつぶしません。
• マイクロ単位に対応 — アシスタントが人間に読みやすい通貨で表示できるよう、すべてのツールの説明でマイクロ単位の規則を解説しています。
• カーソルによるページネーションをそのまま利用できます（limit、order、after、before）。
• npx でインストール不要 — npx -y @hypd-ai/openai-ads-mcp を実行するだけで、クローンやビルドは不要です。

ツール

ツール	機能
get_ad_account	設定済みのキーに対応する広告アカウントを取得します。接続確認に最適です。
list_campaigns	キャンペーン（目的、予算、国別ターゲティング）を一覧表示します。
get_campaign	ID を指定してキャンペーンを 1 件取得します。
list_ad_groups	広告グループを一覧表示します。キャンペーンで絞り込むこともできます。
get_ad_group	ID を指定して広告グループを 1 件取得します（入札設定、コンテキストヒント）。
list_ads	広告を一覧表示します。広告グループで絞り込むこともできます。
get_ad	ID を指定して広告を 1 件取得します（クリエイティブと審査ステータス）。
get_account_insights	アカウント全体のパフォーマンスインサイトを取得します。
get_campaign_insights	キャンペーン 1 件のパフォーマンスインサイトを取得します。
get_ad_group_insights	広告グループ 1 件のパフォーマンスインサイトを取得します。
get_ad_insights	広告 1 件のパフォーマンスインサイトを取得します。

インサイトツールでは、レポート期間を指定する since／until（YYYY-MM-DD）に加え、time_granularity（daily／none）、aggregation_level、fields、sort、filters、limit（1–10000）、after／before のカーソルを指定できます。

前提条件

• Node.js 20 以降。
• OpenAI Ads API キー。 ads.openai.com で Ads アカウントを作成し（現在は米国のみ）、Settings → ads.openai.com/settings からキーを発行してください。クイックスタートと認証のドキュメントを参照してください。各キーは単一の広告アカウントにスコープが設定されています。

インストールと設定

MCP クライアントはサーバーをサブプロセスとして起動し、環境変数を介して API キーを渡します。

npm で@hypd-ai/openai-ads-mcpとして公開されています。npxが自動で取得するため、クローンやビルドは不要です。最新の未リリース版mainを実行するには、@hypd-ai/openai-ads-mcpをgithub:HYPD-AI/openai-ads-mcpに置き換えてください（初回起動時にソースからビルドされます。ソースからの実行を参照してください）。

以下から使用するクライアントの設定を追加してください。

Claude Desktop

claude_desktop_config.jsonを編集します。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

Claude Desktop を再起動してから、「openai-ads ツールを使って広告アカウントを確認してください」と尋ねてください。

Cursor

~/.cursor/mcp.json（グローバル）または.cursor/mcp.json（プロジェクトごと）に追加します。

{
  "mcpServers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

VS Code

.vscode/mcp.jsonに追加します。VS Code ではinputsを使ってキーの入力を求め、シークレットとして保存できます。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "openai_ads_api_key",
      "description": "OpenAI Ads API key",
      "password": true
    }
  ],
  "servers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "${input:openai_ads_api_key}"
      }
    }
  }
}

その他の MCP クライアント

stdio経由で MCP を通信するクライアントであれば使用できます。環境にOPENAI_ADS_API_KEYを設定して、npx -y @hypd-ai/openai-ads-mcp（またはnode /path/to/dist/index.js）を実行してください。

設定

変数	必須	デフォルト	説明
OPENAI_ADS_API_KEY	はい	—	Bearer トークンとして送信される OpenAI Ads API キーです。
OPENAI_ADS_BASE_URL	いいえ	https://api.ads.openai.com/v1	API のベース URL を上書きします（テストやプロキシで便利です）。

.env.exampleを参照してください。

「micros」について

名前が**_micros**で終わるフィールド（キャンペーンのlifetime_spend_limit_microsや広告グループのmax_bid_microsなど）は、micros 単位で表されます。

1,000,000 micros = 1 unit of the account's currency   (e.g. $1.00 = 1,000,000 micros)

したがって、lifetime_spend_limit_microsが25000000の場合は**$25.00**です。_microsの値を1,000,000で割ると人が読みやすい金額になり、逆に変換するには1,000,000を掛けます。

インサイトの指標は micros 単位ではありません。 spend、cpc、cpmなどのレポート値は、すでにアカウントの通貨で小数として表されています（例：spend: 42.75は$42.75を意味します）。

読み取り専用として設計

このリリースで登録されるのは読み取り（GET）ツールのみで、それぞれに MCP のreadOnlyHintが注釈として付与されているため、適切に動作するクライアントは状態を変更できないことを認識できます。作成、編集、一時停止、削除ができるツールや、予算を消費するツールはありません。書き込み操作は、慎重に検討し、別途レビューを行う段階として追加される予定です（ロードマップを参照してください）。

ソースからの実行

git clone https://github.com/hypd-ai/openai-ads-mcp.git
cd openai-ads-mcp
npm install
npm run build

次に、ビルドしたエントリーファイルを MCP クライアントに指定します。

{
  "mcpServers": {
    "openai-ads": {
      "command": "node",
      "args": ["/absolute/path/to/openai-ads-mcp/dist/index.js"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

MCP Inspector で試す

OPENAI_ADS_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

開発

npm install          # install dependencies
npm run dev          # rebuild on change (tsup --watch)
npm run typecheck    # tsc --noEmit
npm run lint         # eslint
npm run format       # prettier --write
npm test             # vitest
npm run build        # bundle to dist/

プロジェクトの構成：

src/
  index.ts        # bin entry: load config, build server, connect stdio
  server.ts       # buildServer(): McpServer + register all tools
  client.ts       # OpenAIAdsClient: auth, URL building, errors
  config.ts       # environment parsing & validation
  schemas.ts      # shared zod shapes (pagination, insights) + micros note
  tools/          # one file per resource (account, campaigns, ad-groups, ads, insights)
test/             # vitest specs (config, client, in-memory server)

ツールと API の対応

すべてのエンドポイントはベース URL（デフォルトは https://api.ads.openai.com/v1）配下にあります。

ツール	メソッド	エンドポイント
get_ad_account	GET	/ad_account
list_campaigns	GET	/campaigns
get_campaign	GET	/campaigns/{campaign_id}
list_ad_groups	GET	/ad_groups
get_ad_group	GET	/ad_groups/{ad_group_id}
list_ads	GET	/ads
get_ad	GET	/ads/{ad_id}
get_account_insights	GET	/ad_account/insights
get_campaign_insights	GET	/campaigns/{campaign_id}/insights
get_ad_group_insights	GET	/ad_groups/{ad_group_id}/insights
get_ad_insights	GET	/ads/{ad_id}/insights

ロードマップ

• ✍️ 書き込み操作 — キャンペーン、広告グループ、広告の作成と更新（POST を使用）、および専用の状態遷移（POST .../activate、.../pause、.../archive）。HTTP クライアントはすでに POST に対応しています。配信状況や費用に影響するため、明示的なオプトインを条件に有効化します。
• 🖼️ クリエイティブのアップロード — POST /upload（JSON の image_url または multipart/form-data）で、広告クリエイティブに画像を添付します。
• 🌍 キャンペーンのターゲティング — 国の包含／除外（targeting.locations.countries）。
• 📈 Conversions API への対応。
• 🌐 ホスト型デプロイメント向けの リモート／HTTP トランスポート。
• 📦 npm リリースの公開により、npx -y openai-ads-mcp をすぐに利用できるようにします。

コントリビューション

コントリビューションを歓迎します！CONTRIBUTING.md をお読みください。要点として、大きな変更については issue を作成して相談し、npm run lint && npm run typecheck && npm test が成功する状態を維持し、新しい動作にはテストを追加してください。

免責事項

これはコミュニティによる非公式プロジェクトです。OpenAI との提携、承認、後援関係はありません。「OpenAI」および関連する名称やロゴは、OpenAI の商標です。このツールを通じた OpenAI Ads API の利用には、OpenAI の利用規約とポリシーが適用されます。このツールは、いかなる保証もなく「現状のまま」提供されます。ライセンスをご覧ください。

ライセンス

MIT © HYPD AI