Apple Ads

この動画では、サンプルデータを使ったホスト版 getmcpads を紹介しています。クリエイティブギャラリーやアラートから Google Sheets へのエクスポート、一括公開まで、MCP Apps はホスト版製品に含まれます。このリポジトリでは、スタンドアロンのネイティブ API ツールを提供します。

読み取りツール 9 個 · 書き込みツール 11 個。デフォルトでは無効です。

独自のプラットフォーム認証情報と、Claude Desktop、Claude Code、Cursor など stdio MCP に対応したクライアントを使ってローカルで実行できます。リクエストはプラットフォームに直接送信されます。対応する ChatGPT 環境を含む管理接続を利用するには、ホスト版をご利用ください。

新着情報

v1.0.0：初のスタンドアロンリリース · 2026 年 10 月 23 日

• Apple Ads Platform API v1 に対応した初のスタンドアロンサーバーを作成し、getmcpads ゲートウェイのリビジョン 3e1c2c8 と同期しました。
• 読み取りツール 9 個、オプトイン方式の書き込みツール 11 個、リソース 2 個を公開し、ゲートウェイのツール名と apple_ads_ プレフィックスを維持します。
• ホスト版のアカウント選択機能に代わる apple_ads_list_ad_accounts を追加しました。設定済みのアカウントのみを返します。
• 環境変数から読み込んだ EC P-256 キーを使い、OAuth 2 クライアント認証情報をローカルで署名します。アクセストークンはメモリ内に保持されます。
• 広告アカウントの許可リストを必須とし、デフォルトで読み取り専用に設定します。すべての書き込み操作を事前にプレビューし、更新をスナップショットに紐付け、エンティティを一時停止状態で作成します。
• 固定の Apple ホストを使用し、リダイレクトを拒否して、レスポンスサイズを制限し、リクエストにタイムアウトを設定します。不確実な書き込み操作は再試行しません。
• Node.js 22.23.4、24.22.1、26.12.1 以降を必須とし、古いランタイムで起動した場合は stderr に警告を出力します。
• ホスト版のアラート、クリエイティブ UI、MCP Apps 連携は含まれません。

完全な変更履歴 · すべてのリリース

ソースの同期状況：SOURCE_SYNC.md。

アップグレードに関する注意

Node.js 22.23.4、24.22.1、26.12.1、またはこれらの系列のより新しいリリースが必要です。これらのリリースには、2026 年 10 月のセキュリティ修正が含まれています。古いランタイムでサーバーを起動すると、stderr に警告が出力されます。CI では Node 22、24、26 を対象としています。書き込み機能は任意であり、明示的な確認が必要です。ホスト版のアラート、クリエイティブ連携、MCP Apps UI は今回のリリースには含まれません。

このリリースをインストールする

これは GitHub のソースリリースです。npm と MCP Registry のバージョンは別途公開されます。以下のコマンドでは、この正確なバージョンを指定します。npm パッケージの公開後は、npx -y @getmcpads/apple-ads-mcp-server を実行すると、npm で現在公開されているバージョンが実行されます。

git clone --branch v1.0.0 --depth 1 https://github.com/get-mcp-ads/apple-ads-mcp-server.git
cd apple-ads-mcp-server
npm ci
npm run build

MCP クライアントで、絶対パスで指定した dist/cli.js と、以下に記載するプラットフォームの認証情報を使って node を実行するように設定します。Claude Desktop の場合：

{
  "mcpServers": {
    "apple-ads": {
      "command": "node",
      "args": ["/absolute/path/to/apple-ads-mcp-server/dist/cli.js"],
      "env": {
        "APPLE_ADS_CLIENT_ID": "SEARCHADS.your-client-id",
        "APPLE_ADS_TEAM_ID": "SEARCHADS.your-team-id",
        "APPLE_ADS_KEY_ID": "your-key-id",
        "APPLE_ADS_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem",
        "APPLE_ADS_AD_ACCOUNT_IDS": "123456789"
      }
    }
  }
}

npm run doctor は Apple に接続せずに、設定と Node.js のリリースを確認します。

管理された接続をお望みですか？ ホスト型 getmcpads で Apple Ads を使用する。アカウントを接続し、アシスタントがアクセスできるデータを選択して、ホスト型 MCP 接続を使用できます。最新の機能とプランについては、サイトをご覧ください。

設定

Apple Ads Platform API は OAuth 2 クライアント認証情報を使用します。クライアントシークレットは有効期間の短い JWT で、このサーバーが秘密鍵で署名し、1 時間有効なアクセストークンと交換します。Apple の OAuth ガイドに従ってください。

1. EC P-256 鍵ペアを生成し、秘密鍵を安全に保管します。

   openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
   openssl ec -in private-key.pem -pubout -out public-key.pem
   

2. API ユーザーとしてサインインした状態で Apple Ads を開き、Account Settings > API に移動して公開鍵を貼り付け、保存します。
3. 公開鍵フィールドの上に表示される clientId、teamId、keyId をコピーします。

クライアントのシークレット設定を通じて、以下の環境変数を指定します。

変数	用途
APPLE_ADS_CLIENT_ID	Account Settings > API に表示される clientId です。
APPLE_ADS_TEAM_ID	Account Settings > API に表示される teamId です。
APPLE_ADS_KEY_ID	Account Settings > API に表示される keyId です。
APPLE_ADS_PRIVATE_KEY_PATH	暗号化されていない PEM 秘密鍵の絶対パスです。これか APPLE_ADS_PRIVATE_KEY のいずれかを設定します。
APPLE_ADS_PRIVATE_KEY	パスの代わりに指定する PEM テキストそのものです。エスケープされた \n 改行を使用できます。
APPLE_ADS_AD_ACCOUNT_IDS	必須の広告アカウント ID。カンマ区切りで 1～200 個指定します。すべてのリクエストはこれらのアカウントに制限されます。
APPLE_ADS_ENABLE_WRITES	デフォルトは false です。完全一致する値 true を指定した場合にのみ、書き込みが有効になります。

鍵は起動時に一度だけ読み込まれ、メモリ内に保持されます。PKCS #8 形式と SEC1 PEM 形式の両方を使用できます。このパッケージは OAuth のブラウザーフローを実行せず、ディスクへの書き込みも行いません。アカウントスコープのリクエストには、Platform API の要件に従って X-AP-Context: adAccountId=<id> ヘッダーが付与されます。まず apple_ads_list_ad_accounts を呼び出してください。これにより、API ユーザーが設定済みのどのアカウントに、どのロールでアクセスできるかを確認できます。

安全性と対象範囲

書き込みはデフォルトでプレビューされます。呼び出しを confirm: true を指定して再実行する前に、対象のアカウント、ターゲット、パラメーターを正確に確認してください。 更新プレビューでは、リソースと変更内容の expectedSnapshot が返されます。確認済みの呼び出しではこれを渡す必要があるため、その間に変更されたリソースが上書きされることはありません。 キャンペーン、広告グループ、キーワードは一時停止状態で作成されます。ステータスを ENABLED に設定すると広告費が発生する可能性があり、プレビューでは activationMaySpend で示されます。 結果が不確かな場合、書き込みを自動的に再試行しないでください。まずエンティティを読み取り、状況を照合してください。自動で再試行されるのは、アクセストークンの更新後に読み取りをもう一度行う場合のみです。 アカウントの許可リストはディスパッチ前に適用され、アカウントの検出結果をフィルタリングします。親子関係も確認されるため、別の広告アカウントに属するキーワードや広告は拒否されます。不明な引数は拒否されます。

リクエストの送信先は api.ads.apple.com と appleid.apple.com のみです。リダイレクトは拒否され、リクエストにはタイムアウトが設定され、レスポンスのサイズには上限があります。エラーメッセージには、Apple のステータス、固定コード、検証済みの検証パスのみが含まれます。値や認証情報が含まれる可能性のあるプロバイダーのテキストは含まれません。 金額には Apple のネイティブオブジェクトを使用します。アカウントの通貨を指定した主要通貨単位の10進数金額です。例：{"amount":"1.50","currency":"EUR"}。ネイティブのページネーション、アトリビューション指標、レポートの合計、総計は保持されます。リストとレポートのレスポンスには nextOffset が追加され、最後のページでは null になります。

このサーバーは Apple Ads Platform API v1 を使用します。Apple は変更履歴で、Platform API が Campaign Management API に取って代わり、同 API は2027年1月26日に終了すると明記しています。 このサーバーが公開するのは、ホステッドゲートウェイと同期されたレビュー済みの機能範囲である、App Store の検索結果キャンペーン、広告グループ、キーワード、広告名の変更、アプリ、レポートです。除外キーワード、クリエイティブ、製品ページ、予算オーダー、一括操作、インサイト、レコメンデーション、Apple Maps 広告は含まれません。 正確なスキーマは tools/list または server-card.json を使用して確認してください。

ホステッドオプション

Apple Ads 用 getmcpads では、ホステッド接続とアカウント選択を管理できます。 ホステッド版とソースリリース版では内容が異なる場合があります。お問い合わせ先：[email protected]。

開発

npm run typecheck
npm run lint
npm run build
npm test
npm run catalog

すべてのテストは、合成レスポンスとモックされた fetch を使用してオフラインで実行されます。実際のアカウントが読み取られたり変更されたりすることはありません。

ツール

すべてのツールを以下に示します。パラメーターと出力の完全なスキーマについては、server-card.jsonを参照してください。

9 個の読み取りツール

ツール	用途
apple_ads_list_ad_accounts	API ユーザーがアクセスできる、設定済みの広告アカウントと組織およびロールを一覧表示します
apple_ads_get_account	通貨、タイムゾーン、請求設定を含む広告アカウントを読み取ります
apple_ads_get_campaigns	キャンペーンのページを読み取り、必要に応じてステータスで絞り込みます
apple_ads_get_campaign	1 つのキャンペーンを読み取り、その広告アカウントに属していることを確認します
apple_ads_get_adgroups	1 つのキャンペーンの広告グループのページを読み取ります
apple_ads_get_keywords	1 つの広告グループのポジティブキーワードのページを読み取ります
apple_ads_get_app	広告アカウントで利用できる App Store アプリのメタデータを読み取ります
apple_ads_get_app_eligibility	キャンペーン作成前に、アプリの広告掲載資格とストアフロントを確認します
apple_ads_get_report	キャンペーン、広告グループ、広告、キーワードまたは検索語句のパフォーマンスを、ネイティブの合計値とともに読み取ります

11 個の書き込みツール

デフォルトでは無効です。明示的に確認されない限り、呼び出しはプレビューを返します。使用前に設定と正確なスキーマを確認してください。

ツール	用途
apple_ads_create_campaign	対象アプリの App Store 検索結果キャンペーンを一時停止状態で作成します
apple_ads_create_adgroup	検証済みのキャンペーン内に、手動のタップ単価制広告グループを一時停止状態で作成します
apple_ads_create_keyword	検証済みの広告グループ内に、ポジティブキーワードを一時停止状態で作成します
apple_ads_create_account	API ユーザーの組織に広告アカウントを作成します
apple_ads_update_campaign	プレビューのスナップショットに紐付けて、キャンペーンの名前、ステータスまたは 1 日の予算を変更します
apple_ads_update_adgroup	プレビューのスナップショットに紐付けて、広告グループの名前またはステータスを変更します
apple_ads_update_keyword	プレビューのスナップショットに紐付けて、キーワードのステータスまたは入札額を変更します
apple_ads_rename_campaign	キャンペーンの名前を変更します
apple_ads_rename_adgroup	広告グループの名前を変更します
apple_ads_rename_ad	広告の名前を変更します
apple_ads_rename_ad_account	広告アカウントの名前を変更し、名前のみを送信します

リソース

リソース	内容
apple-ads://guide	アカウントの適用範囲、金額の単位、レポートのルール、ページネーション、書き込みの安全性
apple-ads://report-catalog	ネイティブのレポート指標、加算可能な指標、グループ化のディメンション、各レポートレベルのルール

ライセンス

Apache License 2.0。NOTICEを参照してください。

getmcpads のその他のサービス

Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

getmcpadsのEmmanuelがメンテナンスしています。お問い合わせ：[email protected]。