apple-search-ads-mcp

Apple Search Ads (現 Apple Ads) Campaign Management API v5を完全にラップするModel Context Protocol (MCP) サーバーです。74種類の型付きツールを備え、キャンペーン、広告グループ、広告、クリエイティブ、カスタムプロダクトページ、キーワード、除外キーワード、レポート、インプレッションシェアレポート、予算オーダー、ACL、地域/アプリ検索、アプリメタデータ、審査不合格理由の監査など、文書化されたすべてのv5エンドポイントと1:1で対応しています。さらに、将来のエンドポイントにも対応可能なRawパススルー機能も備えています。

APIライフサイクル: Apple Ads (Search Ads) v5は現在のプロダクションAPIです。v5は2027年1月26日に終了し、2026年夏に登場する新しい「Apple Ads Platform API」に移行します。このサーバーはv5.0からv5.5を対象としています。

クイックインストール

git clone https://github.com/AppVisionOS/apple-search-ads-mcp.git
cd apple-search-ads-mcp
npm install
npm run build

次に、Claude Codeに1行で登録します：

claude mcp add apple-search-ads --scope user \
  -e ASA_CLIENT_ID=SEARCHADS.xxxx \
  -e ASA_TEAM_ID=SEARCHADS.xxxx \
  -e ASA_KEY_ID=xxxx \
  -e ASA_PRIVATE_KEY_PATH=/absolute/path/to/asa-private.p8 \
  -e ASA_ORG_ID=1234567 \
  -- node $(pwd)/dist/index.js

セットアップ

1. API認証情報の取得

Apple AdsのUIでは、認証情報は2つの画面に分かれています。アカウント設定内のAPIタブはサードパーティサービスプロバイダーのアクセス管理のみを行います。独自のプログラムによるアクセスの場合は、まずユーザー管理からフローを進める必要があります。

a) APIユーザーの招待

app-ads.apple.com → アカウント設定 → ユーザー管理 → ユーザーを招待:

• メールアドレス: 管理可能なアドレス（自身のアドレスでも可。AppleはAPIユーザー用に別のApple IDを要求します）

• ロール: API権限を持つもの（例: APIアカウントマネージャー）

• 招待を送信し、招待された受信トレイから承諾します

b) ローカルでのキーペア生成

招待が処理されている間に、マシン上でES256キーペアを生成します。必ずPKCS#8形式にしてください。Appleの.p8の例や古いopenssl ecparamの出力はPKCS#8ではなく、joseでは読み込めません。

# CORRECT — produces PKCS#8 (-----BEGIN PRIVATE KEY-----)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out asa-private.p8
openssl ec -in asa-private.p8 -pubout -out asa-public.pem

# If you already produced traditional EC (-----BEGIN EC PRIVATE KEY-----), convert it:
#   openssl pkcs8 -topk8 -nocrypt -in asa-private.p8 -out asa-private-pkcs8.p8

asa-private.p8は安全な場所（例: ~/.apple-search-ads/, chmod 600）に保管してください。Appleには公開鍵のみを貼り付けます。

c) APIクライアントの生成

サインアウトし、招待されたAPIユーザーとして（管理者アカウントではなく）再度サインインします。アカウント設定 → APIに移動します。公開鍵のテキストエリアがあるクライアント認証情報画面が表示されます。これはAPIロールを持つユーザーにのみ表示されます。

1. asa-public.pemの内容（-----BEGIN PUBLIC KEY----- / -----END PUBLIC KEY-----マーカーを含む）を貼り付けます。

2. APIクライアントを生成をクリックします。

3. Appleが表示する3つの値（クライアントID、チームID、キーID）をコピーします。これらは後で再表示されません。

2. インストール

npm install
npm run build

3. 設定

.env.exampleを.envにコピーして記入するか、MCPクライアントを通じて環境変数を渡します。

ASA_CLIENT_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ASA_TEAM_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ASA_KEY_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ASA_PRIVATE_KEY_PATH=/absolute/path/to/private-key.p8
ASA_ORG_ID=1234567   # optional default; can be overridden per call

ASA_PRIVATE_KEY（PEMの内容をインラインで記述。JSON経由で注入する場合は\nエスケープが必要）は、ASA_PRIVATE_KEY_PATHの代わりとしてサポートされています。

4. MCPクライアントへの接続

{
  "mcpServers": {
    "apple-search-ads": {
      "command": "node",
      "args": ["/absolute/path/to/apple-search-ads-mcp/dist/index.js"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.xxxx...",
        "ASA_TEAM_ID": "SEARCHADS.xxxx...",
        "ASA_KEY_ID": "xxxx...",
        "ASA_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.p8",
        "ASA_ORG_ID": "1234567"
      }
    }
  }
}

認証

このサーバーは、ES256 JWTクライアントアサーションを使用したOAuth 2.0クライアント認証フローを処理します：

1. .p8秘密鍵でJWTに署名します（ヘッダー: kid=キーID, alg=ES256; ペイロード: iss=チームID, sub=クライアントID, aud=https://appleid.apple.com）。

2. grant_type=client_credentialsおよびscope=searchadsorgを指定してhttps://appleid.apple.com/auth/oauth2/tokenにPOSTします。

3. 返された1時間有効なアクセストークンを、すべてのAPI呼び出しでAuthorization: Bearer …およびX-AP-Context: orgId=…として使用します。

トークンは有効期限の約30秒前までメモリにキャッシュされるため、1時間ごとに1つのアサーションに署名し、1つのトークンを交換します。401エラーが発生した場合、サーバーは強制的にリフレッシュして1回再試行します。429/5xxエラーの場合は、（Retry-Afterを尊重しつつ）最大3回までバックオフします。

ツール一覧（74ツール）

アカウントとアクセス (2)

org_acls, me_user — 組織コンテキストなしで呼び出し、トークンで何ができるかを確認します。

ディスカバリー (3)

search_apps, search_geo, geo_lookup

アプリメタデータ (6)

apps_get, apps_locale_details, apps_eligibilities_find, apps_assets_find, creative_app_preview_devices, countries_or_regions_list

カスタムプロダクトページ (3)

cpp_list, cpp_get, cpp_locale_details

キャンペーン (6)

campaigns_create, campaigns_get, campaigns_list, campaigns_find, campaigns_update, campaigns_delete

広告グループ (7)

adgroups_create, adgroups_get, adgroups_list, adgroups_find_in_campaign, adgroups_find_org_wide, adgroups_update, adgroups_delete

クリエイティブ (4)

creatives_create, creatives_list, creatives_get, creatives_find — クリエイティブはカスタムプロダクトページ、デフォルトプロダクトページ、またはクリエイティブセットの参照をラップします。広告はcreativeIdを介してクリエイティブに紐付けられます。

広告 (7)

ads_create, ads_get, ads_list, ads_find_in_campaign, ads_find_org_wide, ads_update, ads_delete

ターゲティングキーワード (7)

targeting_keywords_create, targeting_keywords_get, targeting_keywords_list, targeting_keywords_find, targeting_keywords_update, targeting_keywords_delete (一括), targeting_keywords_delete_single

除外キーワード — 広告グループスコープ (6)

adgroup_negative_keywords_create, adgroup_negative_keywords_get, adgroup_negative_keywords_list, adgroup_negative_keywords_find, adgroup_negative_keywords_update, adgroup_negative_keywords_delete

除外キーワード — キャンペーンスコープ (6)

campaign_negative_keywords_create, campaign_negative_keywords_get, campaign_negative_keywords_list, campaign_negative_keywords_find, campaign_negative_keywords_update, campaign_negative_keywords_delete

レポート (7)

すべてstartTime, endTimeを受け付けます。オプションでgranularity (HOURLY/DAILY/WEEKLY/MONTHLY)、groupBy (adminArea / ageRange / countryCode / countryOrRegion / deviceClass / gender / locality)、selector、returnRowTotals、returnGrandTotals、returnRecordsWithNoMetrics、timeZone (UTC | ORTZ) を指定可能です。

インプレッションシェアレポート (3) — 非同期

custom_reports_create → reportIdを返します。state=COMPLETEDになるまでcustom_reports_getでポーリングします。custom_reports_listで一覧表示します。

予算オーダー (4) — LOCアカウントのみ

budget_orders_create, budget_orders_get, budget_orders_list, budget_orders_update。v5には予算オーダーの削除機能はありません。

審査不合格理由の監査 (2)

product_page_reasons_find, product_page_reasons_get — Appleの審査担当者がクリエイティブを却下した理由を読み取り専用で確認します。

エスケープハッチ (1)

apple_search_ads_request — 任意のパスとメソッドで呼び出します。認証と組織コンテキストは引き続き自動的に処理されます。

セレクター

*_findツールはAppleのセレクター文法を受け付けます：

{
  "conditions": [
    { "field": "status", "operator": "EQUALS", "values": ["ENABLED"] },
    { "field": "countriesOrRegions", "operator": "CONTAINS_ANY", "values": ["US", "GB"] }
  ],
  "fields": ["id", "name", "status"],
  "orderBy": [{ "field": "name", "sortOrder": "ASCENDING" }],
  "pagination": { "limit": 100, "offset": 0 }
}

演算子: EQUALS, NOT_EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, GREATER_THAN, LESS_THAN, IN, NOT_IN, CONTAINS_ALL, CONTAINS_ANY, BETWEEN。valuesは常に配列です。

エンドツーエンドの例

Claudeを通じて完全に実行可能なワークフロー：

1. org_acls → orgIdを選択。

2. search_appsでアプリを検索 → adamIdを取得。

3. そのadamId、日次予算、米国ターゲティング、adChannelType=SEARCH, supplySources=["APPSTORE_SEARCH_RESULTS"], billingEvent=TAPSを指定してcampaigns_createを実行。

4. キャンペーン内でdefaultBidAmount={amount:"1.00",currency:"USD"}, pricingModel=CPCを指定してadgroups_createを実行。

5. {text, matchType, bidAmount}の行のバッチでtargeting_keywords_createを実行。

6. cpp_list → productPageIdを選択 → type=CUSTOM_PRODUCT_PAGEでcreatives_createを実行してcreativeIdを作成 → ads_createで広告グループに紐付け。

7. 数日待つ。reports_campaignsでトップラインを確認し、reports_search_terms_in_campaignで新しいキーワード/除外キーワードを収集。

8. 上位検索のインプレッションシェア/シェアオブボイスについてcustom_reports_createを実行。

既知の注意点 (v5の癖)

• レガシーなクリエイティブセットのCRUDはありません。 Appleはv5で削除しました。代わりにcreatives行を作成し、ads.creativeIdから参照してください。

• アプリカテゴリのエンドポイントはありません。 apps_getを使用してprimaryGenre / secondaryGenreを読み取ってください。

• 郵便番号による地域ターゲティングはありません。 v5の地域エンティティは国 / 管理区域 / 地域のみです。

• キーワードや広告グループスコープのキーワード検索に対する組織全体の検索はありません。 Appleはターゲティングキーワードの検索をキャンペーンレベル（/campaigns/{id}/adgroups/targetingkeywords/find）でスコープし、広告グループ全体で集計します。絞り込むにはセレクターでadGroupIdを指定してください。

• 予算オーダーのDELETEはありません。 更新してください（削除はできません）。

• オーディエンス、予測、コンバージョンイベントはv5には含まれていません。 これらは別のApple API（AdServices Attributionなど）に存在します。

ローカル開発

npm run dev        # tsc --watch
npm run typecheck  # one-shot type check
npm run build      # compile to dist/

apple_search_ads_requestを使用して任意のエンドポイントを直接デバッグしてください。Appleが返した正確なレスポンス形状を確認できるよう、生のエンベロープを返します。