aapl-ads-mcp

Claude（およびMCP互換クライアント）をApple Search Ads API v5に接続するMCPサーバーです。

概要

MCP (Model Context Protocol) は、AIアシスタントが外部ツールを呼び出すためのオープン標準です。このサーバーはMCP stdioトランスポートを実装しており、Apple Search Adsアカウント（キャンペーン、広告グループ、キーワード、パフォーマンスレポート）をクエリするための9つの読み取り専用ツールを提供します。

一度インストールしてClaude Desktopに設定すれば、自然言語で質問できるようになります。例：「先月最もインストール数を獲得したキーワードは？」「今週インプレッションがゼロのキャンペーンを表示して。」

Related MCP server: tiktok-ads-mcp

目的

公式のASAダッシュボードは人間が見るには適していますが、アドホックな分析や自動レポート作成には不向きです。既存のMCP代替ツールはSaaS型（キーを預ける必要がある）か、メンテナンスされていないものがほとんどです。これは、自分で管理できるオープンソースのセルフホスト型オプションです。

機能

• list_orgs — 認証の確認、アクセス可能な組織の一覧表示

• list_campaigns — キャンペーンの列挙、ステータスによるフィルタリング（オプション）

• list_ad_groups — 指定したキャンペーンの広告グループ

• list_keywords — 入札単価とマッチタイプを含むターゲットキーワード

• get_campaign_report — キャンペーンごとのインプレッション、タップ、インストール、支出、CPI、TTR

• get_ad_group_report — 広告グループごとの同様の指標

• get_keyword_report — キーワードごとのパフォーマンス（週次/日次/月次の粒度）

• get_search_terms_report — 広告をトリガーした実際の検索クエリ（発見に最も役立ちます）

すべてのツールはデフォルトで過去30日間を対象とします。レポートは HOURLY、DAILY、WEEKLY、MONTHLY の粒度をサポートしています。

制限事項

• 設計上、読み取り専用です。 本リリースでは書き込み操作（作成、更新、一時停止）はできません。

• Apple Search Ads Campaign Management APIへのアクセスが必要です。 ASAアカウントでAPIユーザーを作成し、ES256キーペアを生成する必要があります。

• 集計インストール指標はアプリ側の統合なしで機能します。 ASAレポート内の tapInstalls、viewInstalls および関連フィールドはApple Search Adsによって直接入力されるため、アプリ内にSDKは不要です。AdServices / AdAttributionKit は、アプリ内から特定のキャンペーンにインストールを紐付けたい場合（オンボーディングのパーソナライズなど）にのみ必要です。

• 単一組織。 組織IDは設定で固定されます。複数組織の切り替えは実装されていません。

セットアップ

1. ES256キーペアの生成

最新の genpkey コマンドを使用してください。このサーバーが必要とするPKCS#8形式が直接生成されます。古い ecparam -genkey はSEC1形式を生成するため、起動エラーの原因となります。

# Generate private key (PKCS#8)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem

# Derive public key
openssl pkey -in private-key.pem -pubout -out public-key.pem

秘密鍵が -----BEGIN PRIVATE KEY----- で始まっていることを確認してください（-----BEGIN EC PRIVATE KEY----- ではないこと）。ECバリアントで始まる場合は、変換してください：

openssl pkcs8 -topk8 -nocrypt -in ec-key.pem -out private-key.pem

可能であれば private-key.pem はリポジトリのルート外（例: ~/.ssh/asa-private-key.pem）に保存してください。

2. Apple Search AdsでAPIユーザーを作成

1. ASA → Account Settings → User Management に移動します

2. Create User をクリックし、読み取り専用で使用する場合はロールに API Account Read Only を選択します（本サーバーには推奨）。API Campaign Manager も使用可能で、将来的に書き込みツールを追加する予定がある場合はこちらが適しています。

3. API タブに移動し、Create Client をクリックします

4. public-key.pem をアップロードします

5. 確認画面から client_id、team_id、key_id をコピーします

6. Account Settings → Overview で org_id を確認します

3. クローンとビルド

git clone https://github.com/andrealufino/aapl-ads-mcp.git
cd aapl-ads-mcp
npm install
npm run build

4. Claude Desktopの設定

~/Library/Application Support/Claude/claude_desktop_config.json を編集します：

{
  "mcpServers": {
    "aapl-ads": {
      "command": "node",
      "args": ["/absolute/path/to/aapl-ads-mcp/dist/index.js"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.your-client-id-here",

"ASA_TEAM_ID": "SEARCHADS.your-team-id-here",
"ASA_KEY_ID": "your-key-id-here",
"ASA_ORG_ID": "12345678",
"ASA_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem"

} }

} }

注意: ASA_PRIVATE_KEY_PATH は絶対パスである必要があります。チルダ (~) はNode.jsでは展開されないため、フルパスを使用してください。

コンテナやクラウド環境でファイルをマウントするのが現実的でない場合は、代わりに ASA_PRIVATE_KEY にPEMの内容を直接設定してください（改行は保持されます）。両方が設定されている場合は ASA_PRIVATE_KEY が優先されます。

Claude Desktopを再起動します。「run health check」と入力して、サーバーが接続されているか確認してください。

使用例

サーバーが実行されている状態でClaude Desktopで使用できる自然言語プロンプトの例です：

List my Apple Ads campaigns

過去30日間のキャンペーンパフォーマンスを表示して

先週、私のブランドキャンペーンでインストールを促進したキーワードは？

過去1ヶ月間に私の広告をトリガーした検索語句は何ですか？インプレッションはあるがインストールがないものに焦点を当ててください。

2025年第1四半期の全キャンペーンの週次支出を比較して

キャンペーン 1234567890 の広告グループと入札単価を表示して

## Development

```bash
npm run build      # compile TypeScript
npm test           # run test suite (Vitest)
npm run typecheck  # type-check without emitting
npm run lint       # Biome lint
npm run format     # Biome format (write)

MCP Inspector

Claude Desktopを使わずにツール呼び出しを対話的にデバッグするには：

npx @modelcontextprotocol/inspector node dist/index.js

接続前にInspector UIで環境変数を設定してください。

プリコミットフック

クローン後にローカルでlefthookフックをインストールします：

npx lefthook install

これにより以下が設定されます：

• gitleaks protect --staged — シークレットを含むコミットをブロック

• ステージングされた .ts ファイルに対するBiomeリンターチェック

• TypeScriptの型チェック

貢献

技術的な詳細（認証フロー、HTTPクライアント設計、ツールパターン、レポートスキーマの癖、開発中に学んだASA v5の教訓）については docs/ARCHITECTURE.md を参照してください。

バグレポートやプルリクエストを歓迎します。

セキュリティ

• .env や *.pem ファイルは絶対にコミットしないでください（両方とも .gitignore に含まれています）

• private-key.pem はリポジトリのルート外に保管してください

• アクセストークンはメモリ内でのみ保持され、ディスクには書き込まれません

• キーが漏洩した疑いがある場合は、ASA → Account Settings → API でローテーションしてください

ライセンス

MIT — LICENSE を参照してください。