Apple Ads MCP

Apple Ads Platform API v1 向けのローカルファーストな Model Context Protocol サーバーです。Codex、Claude、その他の MCP クライアントに、App Store 広告の調査、レポート、監査、およびレシートで保護されたキャンペーン管理のための型付きツールを提供します。

Apple Ads MCP は独立したオープンソースソフトウェアです。Apple Inc. とは提携しておらず、その承認や後援も受けていません。Apple Ads および App Store は Apple Inc. の商標です。

Apple Ads MCP を選ぶ理由

• エージェントファーストのツール: 所有アプリの検出、キーワード調査、レポート確認、キャンペーン監査、および範囲を絞った変更の準備が可能。

• ローカル認証情報: 秘密鍵はお使いのマシンに留まります。OAuth トークンと操作レシートはプロセスメモリ内にのみ保持されます。

• デフォルトで読み取り専用: 調査とレポートはミューテーションを有効にしなくても動作します。

• 明示的なアカウントルーティング: アカウントスコープのすべてのツールにはプロファイルと adAccountId が必要です。

• 安全なミューテーション: すべての書き込みにはプレビュー、10分間有効な使い捨てレシート、および現在の状態の再チェックが必要です。

• 出力の制限: 構造化された MCP コンテンツ、上限付き配列、ページネーション、レート制限メタデータ、および構造化された Apple エラー。

• ポータブルなランタイム: macOS、Linux、Windows 向けの単一の Go バイナリに加え、OCI イメージも提供。

Related MCP server: OpenAI Ads MCP

リリースステータス

v0.1.0 は最初の公開リリースです。完全なローカルテストスイート、レース検出器、静的解析、脆弱性スキャン、シークレットスキャン、配布検証、および実際の MCP stdio テストがすべて合格しています。

オペレーター管理の Apple Ads アカウントに対する非公開のライブ受け入れテストでは、以下が検証されました:

• OAuth、アカウント検出、組織および所有アプリの検索;

• ストアフロントの利用可能性、キーワード提案、人気インサイト、および上限付きレポート;

• プレビュー → レシート → 適用 → 直接 API 読み戻し;

• 一時停止中のキャンペーン、広告グループ、ターゲティングキーワード、および否定キーワードの作成;

• ドリフト拒否、使い捨てレシート、読み取り専用の復元、および広告費ゼロ。

このリポジトリには、認証情報、アカウントのエクスポート、非公開のキャンペーンデータ、またはライブレシートは保存されません。

機能

読み取りツール

レシートで保護された書き込みツール

• キャンペーン、広告グループ、ターゲティングキーワード、および否定キーワードの作成と更新。

• 広告および App Store クリエイティブ用の供給固有のプレビューファンデーションを使用。サポートは Apple のプレースメントとプロダクトページの組み合わせに依存します。

• キャンペーンの一時停止/再開、広告グループの入札、および CPA 上限のプレビュー。

• operations_apply を通じて正確に1つのプレビューを適用。

• operations_inspect および operations_verify を通じて曖昧な操作を検査または検証。

汎用の生リクエストツールはありません。Apple Maps、レガシー Campaign Management API v5、自動予算増額、破壊的な削除、および推奨事項の適用/却下操作は意図的に除外されています。

安全性モデル

ミューテーションは、以下のすべてが真の場合にのみ可能です:

1. Apple ユーザーが明示的な広告アカウントに対して認識された API 書き込みロールを持っている。

2. サーバーが --allow-writes で起動されている。

3. 選択されたプロファイルが allowWrites: true を持っている。

4. 専用の *_preview ツールがレシートを返す。

5. operations_apply が同じ未期限切れのレシートを受け取る。

6. 現在の Apple リソースがプレビュー中に読み取られた状態と一致している。

レシートは10分で期限切れになり、使い捨てです。曖昧な転送障害の後、ミューテーションが再試行されることはありません。サーバーは committed_unverified を返し、後続の書き込みの前に直接の状態チェックを要求します。

通常の調査とレポートでは、--allow-writes なしでサーバーを実行し、すべてのプロファイルを allowWrites: false に保ってください。

インストール

GitHub Releases

お使いのプラットフォーム用のアーカイブを GitHub Releases からダウンロードしてください。各リリースには SHA-256 チェックサムと SPDX SBOM が含まれています。

Apple シリコンの例:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Homebrew フォーミュラ

リリースでは、チェックサムで固定されたフォーミュラがアセットとして公開されます:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp.rb
brew install --formula ./apple-ads-mcp.rb

OCI イメージ

docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.1.0

このイメージはデフォルトで serve --stdio を実行します。accounts.json と参照される秘密鍵を読み取り専用でマウントしてください。鍵がオーナーのみの場合、対応するホスト UID/GID でコンテナを実行してください。

ソースからのビルド

git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./bin/apple-ads-mcp ./cmd/apple-ads-mcp

Go 1.26.6 以降が必要です。

Apple Ads API のセットアップ

Apple Ads API へのアクセスは App Store Connect へのアクセスとは別です。Apple Ads アカウント管理者が、適切なロールを持つ API ユーザーを追加する必要があります。キャンペーン変更が必要になるまでは、API Account Read Only を推奨します。

ES256 鍵ペアをローカルで生成します:

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

公開鍵のみを Apple Ads にアップロードしてください。秘密鍵はリポジトリの外に保管し、エージェントの会話、issue、またはログに貼り付けないでください。

Apple が公開鍵を登録した後、Apple Ads UI に表示される非秘密のクライアント ID、チーム ID、およびキー ID を記録してください。

設定

プロファイルを対話的に作成します:

apple-ads-mcp config init

デフォルトの設定パスは:

~/.config/apple-ads-mcp/accounts.json

同等の JSON:

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false
    }
  ]
}

POSIX システムでは、両方のファイルがオーナーのみの権限である必要があります:

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

設定にはプロファイルのメタデータと秘密鍵のパスのみが保存されます。秘密鍵自体は埋め込まれません。

認証を検証し、アクセス可能なアカウントを検出します:

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

設定の優先順位:

1. --config

2. APPLE_ADS_MCP_CONFIG

3. ~/.config/apple-ads-mcp/accounts.json

4. 単一プロファイルの APPLE_ADS_* 環境変数

サポートされている環境変数は、APPLE_ADS_PROFILE、APPLE_ADS_CLIENT_ID、APPLE_ADS_TEAM_ID、APPLE_ADS_KEY_ID、APPLE_ADS_PRIVATE_KEY_PATH、APPLE_ADS_AD_ACCOUNT_ID、および APPLE_ADS_ALLOW_WRITES です。

MCP クライアントの接続

stdio でサーバーを起動します:

apple-ads-mcp serve --stdio

Codex、Claude Desktop、またはその他の stdio クライアント用の汎用 MCP 設定:

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Claude Code:

claude mcp add apple-ads -- apple-ads-mcp serve --stdio

リリースアーカイブには、Codex プラグインメタデータと apple-ads-operator スキルも含まれています。このスキルは、オンボーディング、調査、キャンペーンワークフロー、およびミューテーションの安全性を、プロンプトに認証情報を置くことなくルーティングします。

1つのセッションで書き込みを有効にする

可能な限り、永続プロファイルでは allowWrites: false を維持してください。明示的に承認されたメンテナンスセッションでは、両方のゲートを一時的に有効にします:

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

Apple ACL、明示的な profile、明示的な adAccountId、プレビュー、レシートのバインド、期限切れ、およびドリフトチェックは引き続き適用されます。書き込みゲート付きでサーバーを起動しても、それ自体では何も変更されません。

既知のプラットフォーム動作

• Apple Ads には公開サンドボックスがありません。自動化されたライブ CI はオプトインであり、厳密に読み取り専用です。

• 利用可能性、提案、人気、推奨事項、およびレポートは、アカウント、アプリ、ストアフロント、およびキャンペーン履歴によって異なります。

• コールドアカウントでは、目標 CPA または予算の推奨事項が返されない場合があります。

• Apple はエンドポイント固有の検証エラーまたはサーバーエラーを返す場合があります。MCP は 4xx 応答の安全な詳細を制限付きで保持し、再試行可能なサーバーエラーは編集して保持します。

• ライブ受け入れテスト中、Apple は APPSTORE_SEARCH_RESULTS 供給ソースの個別の Ad オブジェクトを拒否しました。Search Results はアプリの公開済み Default Product Page を使用しました。

• キャンペーン名は Apple によって検証されます。Web UI で受け入れられる一部の句読点は API で拒否される場合があります。

• パフォーマンスレポートは、配信データが存在するまで空のままです。インストールからサブスクリプションまたはトライアルへの帰属は、この API ではなく、お客様の帰属スタックに属します。

• 完全なアップストリーム MCP コンフォーマンスランナーのカバレッジは保留中です。現在のランナーはサーバー URL を受け入れますが、stdio 子プロセスを起動できないためです。このリポジトリは、公式 Go SDK を通じて実際の stdio セッションをテストします。

開発

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
go run github.com/zricethezav/gitleaks/v8@v8.29.1 dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/v2@v2.17.1 check
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
npx --yes markdownlint-cli2@0.23.2 '**/*.md'
python3 scripts/validate_distribution.py

ライブテストには明示的なローカル認証情報が必要であり、自動的にミューテーションを実行することはありません。CONTRIBUTING.md、SECURITY.md、ロードマップ、および機械可読な操作マトリックスを参照してください。

リリースアーティファクト

タグ付きリリースごとに以下が公開されます:

• サポートされている場合の AMD64 および ARM64 向け macOS、Linux、Windows アーカイブ;

• SHA-256 ダイジェストを含む checksums.txt;

• Syft で生成された SPDX ソフトウェア部品表;

• チェックサムで固定された Homebrew フォーミュラ;

• Linux AMD64 および ARM64 向けのマルチアーキテクチャ OCI イメージ;

• MCP Registry パッケージメタデータ。

ライセンス

MIT