Skip to main content
Glama
aapl-ads-mcp

aapl-ads-mcp

by andrealufino

aapl-ads-mcp

Node version License andrealufino/aapl-ads-mcp MCP server

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

概要

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

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

Related MCP server: Reddit Ads MCP Server

目的

公式の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 を参照してください。

Available Tools

9 tools
get_ad_group_reportA

Fetch performance metrics for ad groups within a specific Apple Search Ads campaign: impressions, taps, TTR, spend, CPI, installs (tap-through and view-through), and install rate. Requires ASA authentication; read-only. Use get_campaign_report for a campaign-level summary, or get_keyword_report for keyword-level detail. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: campaignId (required), endDate, startDate, adGroupIds, +1 more.

get_campaign_reportA

Fetch performance metrics for Apple Search Ads campaigns: impressions, taps, tap-through rate (TTR), localSpend, avgCPT, avgCPM, tapInstalls, viewInstalls, totalInstalls, new downloads, redownloads, CPI, and install rate. Requires ASA authentication; read-only. Use get_ad_group_report or get_keyword_report for deeper breakdowns. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: startDate, endDate, granularity, campaignIds.

get_keyword_reportA

Fetch performance metrics for targeting keywords in a specific Apple Search Ads ad group: impressions, taps, TTR, spend, CPI, installs, and install rate broken down per keyword. Requires ASA authentication; read-only. Use get_search_terms_report to see the actual user queries that triggered these keywords. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.

get_search_terms_reportA

Fetch the actual user search queries that triggered Apple Search Ads impressions, along with performance metrics per search term. Requires ASA authentication; read-only. Most useful for keyword discovery (finding new terms to add) and negation (finding irrelevant queries to exclude). Does not support granularity breakdown — returns aggregate totals per search term. Use get_keyword_report to see metrics for your configured targeting keywords instead. Defaults to the last 30 days.

Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.

healthA

Check if the aapl-ads-mcp server is running and reachable. Use this to verify the MCP connection before making API calls. No ASA authentication is required — returns server name, version, and current timestamp.

Inputs: no named parameters.

list_ad_groupsA

List ad groups within a specific Apple Search Ads campaign. Requires ASA authentication; read-only. Returns ad group metadata (id, name, status, default bid, automated keyword opt-in) but not performance metrics — use get_ad_group_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: campaignId (required), limit, offset.

list_campaignsA

List all campaigns in the configured Apple Search Ads organization. Requires ASA authentication; read-only. Returns campaign metadata (id, name, status, budget, country, channel type) but not performance metrics — use get_campaign_report for metrics. Optionally filter by status. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: status, limit, offset.

list_keywordsA

List targeting keywords for a specific Apple Search Ads ad group. Requires ASA authentication; read-only. Returns keyword metadata (text, match type BROAD/EXACT, bid amount, status) but not performance metrics — use get_keyword_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: campaignId (required), adGroupId (required), limit, offset.

list_orgsA

List all Apple Search Ads organizations accessible with the configured credentials. Requires ASA authentication. Use this to verify credentials are valid and to discover available org IDs before calling other tools. Returns org ID, name, currency, timezone, payment model, and assigned role names.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct entity and action: list_* for enumerating hierarchy levels, get_*_report for metrics at each level, get_search_terms_report for search queries, and health for server status. No two tools could be confused for the same task.

    Naming Consistency4/5

    Most tools follow the list_ or get_*_report pattern clearly separating metadata enumeration from report retrieval. The single deviation is 'health', which is a noun rather than a verb-prefixed action (e.g., check_health), making the pattern slightly inconsistent.

    Tool Count5/5

    Nine tools is well-scoped for a read-only Apple Search Ads data access server: four list tools for entity hierarchy, four report tools for metrics breakdowns, and a health check. Each tool serves a distinct need without redundancy.

    Completeness4/5

    The read-only surface covers the full object hierarchy (org → campaign → ad group → keyword) with list operations and corresponding report endpoints, including search terms. However, the complete absence of write operations (no create/update/delete for campaigns or keywords) could be a gap if management tasks are expected, though it appears intentionally read-only.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Provides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.
      6
      72 PyPI
      46
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only access to Reddit Ads API v3 for listing ad accounts, campaigns, ad groups, ads, and generating performance reports with OAuth2 authentication.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only analysis of Apple Ads Platform data, allowing AI assistants to query campaign structure, keywords, search terms, and performance reports without modifying anything.
      MIT