5分で Apple Search Ads を Claude または ChatGPT に接続する

Hermoso の Apple Search Ads コネクターは、Apple Ads アカウントを Claude、ChatGPT、Cursor、CLI、または通常の HTTP に接続し、エージェントが App Store の検索広告を運用できるようにします。キャンペーン、広告グループ、ターゲティングのキーワードとネガティブキーワードを作成し、Apple に実際に保存された内容を読み戻します。さらに、ユーザーがインストール前に入力した検索語句まで掘り下げてパフォーマンスを報告します。作成したものはすべて一時停止の状態で作られ、配信費用を有効にする操作は、別途明示的に確認する手順になっています。レポートは Google スプレッドシート、Looker Studio のダッシュボード、JSON ファイルに出力できます。コネクターにできることの一覧は Apple Ads MCP のページにあります。

接続には約5分かかります。openssl を実行する必要はなく、Apple のパスワードが Hermoso に渡ることもありません。

Claude に Apple Search Ads を接続する

Claude に Apple Search Ads を接続するには、まず Hermoso を Claude のコネクターとして追加し、続いて Hermoso の中で Apple Ads アカウントを一度接続します。Claude で Customize › Connectors › Add custom connector を開き、名前を Hermoso にして https://app.hermoso.ai/mcp を貼り付け、ご自身の Hermoso アカウントで承認してください。Claude に貼り付ける鍵はありません。次に、このページの後半の手順に従い、Hermoso の 設定 › コネクター から Apple Ads を接続します。これ以降、Claude は Hermoso が持つ Apple Ads のツールをすべて呼び出せます。レポートの取得、キーワードの変更、新しいキャンペーンの作成を、普通の言葉で頼むだけです。Claude Code では、代わりに2つのコマンドを実行します。/plugin marketplace add hermoso-ai/hermoso の後に /plugin install hermoso@hermoso です。全手順は Claude での Hermoso にまとめています。

ChatGPT に Apple Search Ads を接続する

ChatGPT も同じ手順です。ChatGPT で Plugins を開き、Add › Create MCP App を選んで、名前を Hermoso にします。Server URL に https://app.hermoso.ai/mcp を貼り付け、認証は OAuth のままにして、ご自身の Hermoso アカウントで承認してください。Create MCP App が見当たらない場合は、Settings › Plugins › Developer mode で一度 Developer mode をオンにします。Hermoso で Apple Ads を接続済みであれば、ChatGPT はキーワードのレポートを取得したり、Google スプレッドシートに書き込んだり、キャンペーンの下書きを作って確認用に渡したりできます。ChatGPT での Hermoso で手順を紹介しています。

Cursor、Codex、その他の MCP クライアント

Model Context Protocol に対応したクライアントなら、どれも同じアドレスで同じツールに接続できます。Cursor は https://app.hermoso.ai/mcp を、その mcp.json から読み込みます。Codex では codex plugin marketplace add hermoso-ai/hermoso で Hermoso のプラグインを追加すると、同じツールをターミナルから操作できます。どのクライアントを使っても、Apple の認証情報がチャットを通ることはありません。エージェントは Hermoso のツールを呼び出し、Hermoso が手元で保持している鍵を使って、Apple へのリクエストに署名します。ツールの一覧は Apple Ads MCP のページ にあります。

接続後に頼めること

• “先週の Apple Search Ads のパフォーマンスをキーワード別に出して、獲得単価 (CPA) が最も高い上位10件を見せて。”
• “過去30日分の費用、インストール数、CPA をキャンペーン別に、『Apple Ads』という名前の新しい Google スプレッドシートにまとめて。”（先に Google Drive を接続してください。）
• “今月、米国キャンペーンでインストールにつながった検索語句のうち、まだ完全一致キーワードとして入札していないものはどれ？”
• “Brand 広告グループに『budget planner』と『expense tracker』を完全一致キーワードとして追加して、『jobs』をネガティブキーワードにして。”
• “Apple が自分のアプリに提案しているキーワードは何か。すでに入札しているキーワードでは、インプレッションのシェアがどれくらいか教えて。”
• “英国向けに、1日50ドルの予算で一時停止中のキャンペーンを作って、Apple に保存された内容を見せて。”

レポートを読んでも費用には一切影響しません。エージェントが作成したものはすべて一時停止の状態で作られ、配信をオンにするスイッチは、ご自身の明示的な確認を待ちます。

まず最初に、多くの人がつまずくこと

Apple の公式手順にはこうあります。“Ads UI で Account Settings › API を選び、Public Key 欄に鍵を貼り付けてください。”

この欄は、アカウント管理者には表示されません。 ご自身のアカウントに管理者としてサインインして Account Settings › API を開くと、Manage API Access という見出しの表が表示されます。第三者のサービスプロバイダーの一覧と、それぞれの Remove Access 操作だけが並び、鍵を入力する欄はページのどこにもありません。機能がないように見えるため、多くの人はここで止まり、API は自分には使えないと判断してしまいます。

実際には使えます。Public Key 欄は API ロールを持つユーザーに表示されるもので、アカウント管理者であることは API ロールには当たりません。Apple の招待ダイアログには6つのロールがあり、そのうち API ロールは2つだけです。

• API Account Manager: “read and write access to all campaign groups for API management”（API 管理のための、すべてのキャンペーングループへの読み取りと書き込みのアクセス）。Hermoso にキャンペーンを作らせたいなら、こちらを選んでください。
• API Account Read Only: “read only access to all campaign groups for API management”（API 管理のための、すべてのキャンペーングループへの読み取り専用のアクセス）。レポートだけなら十分で、それ以外はできません。

残りの4つ (Account Admin、Account Finance、Account Read Only、Limited Access) では、API の認証情報を発行できません。そこで、ご自身宛ての招待を送って解決します。

1. Account Settings › User Management を開き、Invite Users を選びます。
2. ご自身が管理できるアドレスを招待します。自分のアドレスでも、認証情報が一人に依存しないように ads-api@yourcompany.com のような共有アドレスでも構いません。ロールは API Account Manager にしてください。
3. その受信箱から招待を承認し、そのユーザーとして Apple Ads にサインインします。

これで Account Settings › API に Public Key 欄が表示されます。

接続の手順

1. Hermoso で開始します。 設定 › コネクター › Apple Ads › Connect。Hermoso は EC P-256 の署名鍵を生成します。prime256v1 鍵と同じもので、Apple の2つの openssl コマンドで作られるはずだったものです。画面に表示されるのは公開鍵の半分だけです。コピーしてください。
2. 公開鍵を Apple に渡します。 API ロールのユーザーとして Account Settings › API を開き、Public Key に貼り付けて Save します。
3. 3つの ID を戻します。 Apple は、その欄の真上に clientId、teamId、keyId を表示します。3つすべてをコピーしてください。
4. Hermoso で完了させます。 3つの ID を貼り付けて保存します。Hermoso は何かを保存する前に Apple とトークンを交換し、組織の一覧を読み込みます。そのため、ID を打ち間違えていれば、1時間後の最初のレポートで気づくのではなく、貼り付けた内容がまだ見えている今この場で失敗します。
5. 組織を選びます。 認証情報が複数の組織にまたがる場合です。接続は、選んだ1つの組織に固定されます。

うまくいかないときは

API のページに Public Key 欄がありません

Account Admin として、または API ロール以外の4つのロールのいずれかでサインインしている可能性があります。API Account Manager として自分を招待し、そのユーザーとしてサインインしてください (上記を参照)。Apple Ads の接続が完了しない理由として、これが最も多いものです。

Apple が認証情報を拒否します

3つの ID は、Apple が保持している鍵に属している必要があります。Public Key 欄の真上から clientId、teamId、keyId を改めてコピーしてください。以前に置き換えた古い鍵の ID を使ってはいけません。それでも失敗する場合は、Hermoso で接続を最初からやり直してください。新しい鍵ペアが作られるので、その公開鍵の半分を Apple に貼り付けます。

設定のセッションが期限切れになりました

Hermoso は、生成した秘密鍵を24時間保持します。その間に公開鍵の半分を Apple に貼り付けてください。それを過ぎると、意図的に鍵は消去されます。接続を最初からやり直し、新しい公開鍵を貼り付けてください。

openssl で鍵をすでに作ってあります

その鍵をそのまま使えます。接続時に Hermoso の鍵の代わりに、お持ちの EC P-256 秘密鍵を貼り付けてください。Apple アカウントにすでに登録されている公開鍵は引き続き使えます。曲線は EC P-256 (prime256v1) である必要があります。Apple はそれ以外の曲線を受け付けません。

複数の Apple Ads 組織を管理しています

組織ごとに、それぞれ別の Hermoso プロファイルで接続してください。接続は1つの組織に固定されます。これにより、エージェンシーのキャンペーンが別の顧客のアカウントに入ってしまうことを防げます。

Apple Search Ads コネクターでできること

作成と変更: create_apple_ads_campaign、create_apple_ads_ad_group、add_apple_ads_keywords、add_apple_ads_negative_keywords、update_apple_ads_object、set_apple_ads_status、delete_apple_ads_object。

読み取り: list_apple_ads_campaigns (ステータス、配信状態、日次と総予算、キャンペーンが配信される国、配信できない場合は Apple が示す理由)、list_apple_ads_ad_groups (デフォルトの入札額と、Apple の Search Match がオンかどうか)、list_apple_ads_keywords (マッチタイプと入札額を含む、ターゲティングとネガティブの両方)、apple_ads_report (キャンペーン、広告グループ、広告、キーワード、検索語句の各レベルで、インプレッション、タップ、インストール、費用、TTR、CPT、CPA)、list_apple_ads_orgs。

これらはすべて、Claude、Claude Code、Codex、Cursor、Cline、OpenClaw、Hermes、その他の MCP クライアントから呼び出せるほか、Web のスタジオからも使えます。どの経路でも同じエンジンです。詳しくは MCP の概要 または 広告ツールのリファレンス をご覧ください。

さらに: クリエイティブと広告も作成でき (create_apple_ads_creative、create_apple_ads_ad)、1回の呼び出しで最大1,000件のキーワードを読み込めます (bulk_apple_ads_keywords)。Apple 自身のデータも読み取れます。apple_ads_keyword_suggestions、apple_ads_impression_share、apple_ads_search_term_popularity、apple_ads_change_history です。これらはすべて、同じチャットから呼び出せます。

Apple Search Ads のデータをエクスポートする

同じ接続でレポートも取得できます。apple_ads_report は、キャンペーン、広告グループ、広告、キーワード、検索語句ごとのパフォーマンス (インプレッション、タップ、インストール、費用、タップ率、タップ単価、CPA) を、合計として、または時間、日、週、月ごとの系列として、1ページ最大5,000行まで取得します。レポートを読んでも費用は一切発生しません。行の送り先はご自由に選べます。よく使われる3つの送り先を以下に示します。完全なガイドは Apple Search Ads のデータをエクスポートする です。

Apple Search Ads を Google スプレッドシートに接続する

Apple Ads の隣で Google Drive を接続し (Google の1回の認証で Drive、Sheets、Docs が使えます)、エージェントにレポートをスプレッドシートへ入れるよう頼みます。エージェントは apple_ads_report を呼び出し、新しいスプレッドシートなら create_sheet、既存のシートに今週分の行を追加するなら append_to_sheet を使います。Hermoso は Google に drive.file スコープを要求します。これが届くのは Hermoso が作成したファイルと、ご自身が選んだファイルだけで、Drive 全体には届きません。手順の詳細は Apple Search Ads を Google スプレッドシートに接続する にあります。

Apple Search Ads を Looker Studio に書き出す

Hermoso には Looker Studio のネイティブ コネクターがありません。ないものがあるとは書きません。必要もないからです。Looker Studio は Google スプレッドシートを、独自の標準コネクターで読み込めます。そのため、上のシートが橋渡し役になります。一度シートを Google スプレッドシートのデータソースとして追加してダッシュボードを作れば、毎週追加される行は、次回のデータ更新で反映されます。Power BI と Tableau も、同じシートを同じように読み込めます。Looker Studio の手順。

Apple Search Ads を JSON に書き出す

生の行データがほしい場合は、API キーを使って Hermoso の API からツールを呼び出します。POST https://app.hermoso.ai/v1/tools/apple_ads_report に、レポートの引数を JSON ボディとして送ってください。応答の data.rows から行を読み取れます。ターミナルなら、npx -y hermoso call apple_ads_report --json '{...}' --structured が同じ結果を JSON で表示します。リクエストの完全な例。

よくある質問

Apple Search Ads を Claude に接続するには？

Hermoso を、URL https://app.hermoso.ai/mcp のカスタムコネクターとして Claude に追加し、ご自身の Hermoso アカウントで承認してください。その後、設定 › コネクター で Apple Ads を接続します。これで Claude は、Hermoso の Apple Ads ツールを通じて、Apple Search Ads のキャンペーンのレポートを見たり、編集したり、作成したりできます。

ChatGPT は私の Apple Search Ads データを読めますか？

はい。ChatGPT で Plugins › Add › Create MCP App を開き、https://app.hermoso.ai/mcp を追加してください。そのうえで、Hermoso で Apple Ads を接続します。すると ChatGPT は、キャンペーン、広告グループ、広告、キーワード、検索語句ごとに、インプレッション、タップ、インストール、費用、TTR、CPT、CPA を取得し、その行を Google スプレッドシートに書き込めます。

Apple Search Ads の MCP サーバーはありますか？

はい。Hermoso のホスト型 MCP サーバー https://app.hermoso.ai/mcp が、Claude、ChatGPT、Cursor、Codex、その他の MCP クライアントに、Apple Ads の全ツールを提供します。レポート、キャンペーン、広告グループ、キーワードとネガティブキーワード、クリエイティブと広告、Apple のキーワード提案が含まれます。作成されるものはすべて一時停止の状態になります。

Apple Ads API のページに Public Key 欄がないのはなぜですか？

Account Admin としてサインインしているためです。Apple がその欄を表示するのは、API ロールを持つユーザーに対してだけです。管理者には、代わりに第三者のサービスプロバイダーの「Manage API Access」の表が表示され、鍵を入力する欄はページのどこにもありません。Account Settings › User Management で自分を API Account Manager として招待し、そのユーザーとしてサインインすれば、欄が表示されます。

どの Apple Ads ロールが必要ですか？

Hermoso にキャンペーン、広告グループ、キーワードを作らせたいなら API Account Manager です。Apple はこれを「API 管理のための、すべてのキャンペーングループへの読み取りと書き込みのアクセス」と説明しています。レポートだけが必要なら API Account Read Only で足ります。Apple が提供する残りの4つのロール (Account Admin、Account Finance、Account Read Only、Limited Access) では、API の認証情報を発行できません。

openssl を実行する必要がありますか？

いいえ。Apple の手順では openssl コマンドを2つ実行するよう求められますが、Hermoso が EC P-256 の鍵ペアを生成し、公開鍵の半分だけを表示します。リクエストに署名する秘密鍵の半分は、ご自身が目にしたり、貼り付けたり、保存したりすることはありません。別のツールで作った鍵をお持ちなら、それを持ち込むこともできます。

Apple Ads を接続すると費用がかかったり、配信費用が発生するリスクはありますか？

いいえ。レポートの取得は自由に呼び出せます。Hermoso が作成するものはすべて、例外なく一時停止の状態で作られます。オブジェクトを有効にすることだけが実際の配信費用を発生させるスイッチで、それには明示的な確認が必要です。

clientId、teamId、keyId とは何ですか？

公開鍵を保存すると、Apple が Public Key 欄の上に表示する3つの識別子です。これらは API ユーザーを Apple に識別させるためのもので、秘密鍵がそれを本人だと証明します。3つすべてを Hermoso に貼り付ければ、接続は完了です。

1つの接続で複数の Apple Ads 組織をカバーできますか？

1つの接続は、作成時に選んだ1つの組織に固定されます。Apple は orgId をキャンペーングループのようなものとして扱うため、1つのログインで複数の組織をカバーできる場合があります。顧客ごとに組織を持つエージェンシーは、組織ごとに別の Hermoso プロファイルで接続してください。

180日ごとに鍵をローテーションする必要がありますか？

いいえ。Apple はクライアントシークレットの有効期限を180日と定めており、そのため Apple の手順では定期的なローテーションを予定に入れるよう求めています。Hermoso は秘密鍵を保持し、トークンを交換するたびに新しい短時間有効なシークレットを生成するため、期限切れになる設定ファイルは存在しません。

Apple Search Ads のデータを Google スプレッドシートや Looker Studio に書き出せますか？

はい。Hermoso に Apple Ads と並べて Google Drive を接続すると、エージェントが create_sheet または append_to_sheet を使って、レポートを Google スプレッドシートに書き込みます。Hermoso には Looker Studio のネイティブ コネクターがありません。Looker Studio は、そのシートを独自の Google スプレッドシート コネクターで読み込みます。

Apple Search Ads のデータを JSON で取得できますか？

はい。API キーを使って Hermoso API の POST /v1/tools/apple_ads_report を呼び出し、応答の data.rows を読み取ってください。または CLI から、--structured を付けて hermoso call apple_ads_report を実行します。