apple-search-ads-mcp

Сервер протокола контекста модели (MCP), который оборачивает полный API управления кампаниями Apple Search Ads (теперь Apple Ads) v5. 74 типизированных инструмента, прямое соответствие (1:1) каждому задокументированному эндпоинту v5 — кампании, группы объявлений, объявления, креативы, пользовательские страницы продукта, ключевые слова, минус-слова, отчеты, отчеты о доле показов, бюджетные заказы, списки контроля доступа (ACL), гео/поиск приложений, метаданные приложений, аудит причин отклонения — плюс возможность прямого запроса для любых будущих эндпоинтов.

Жизненный цикл API: Apple Ads (Search Ads) v5 — это текущий рабочий API. Поддержка v5 прекращается 26 января 2027 года в пользу нового «Apple Ads Platform API», который появится летом 2026 года. Этот сервер ориентирован на версии 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 одной строкой:

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

Related MCP server: aapl-ads-mcp

Настройка

1. Получение учетных данных API

Интерфейс Apple Ads разделяет учетные данные на два экрана. Вкладка API в настройках аккаунта управляет доступом только для сторонних поставщиков услуг; для вашего собственного программного доступа процесс сначала проходит через Управление пользователями.

а) Приглашение пользователя API

В app-ads.apple.com → Account Settings → User Management → Invite User:

• Email: любой адрес, который вы контролируете (может быть вашим собственным; Apple требует отдельный Apple ID для пользователя API)

• Роль: выберите ту, у которой есть разрешения API (например, API Account Manager)

• Отправьте приглашение, затем примите его из почтового ящика приглашенного пользователя

б) Генерация пары ключей локально

Пока приглашение обрабатывается, сгенерируйте пару ключей 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 только публичную часть.

в) Генерация клиента API

Выйдите из системы и войдите снова как приглашенный пользователь API (не под учетной записью администратора). Перейдите в Account Settings → API. Вы увидите экран Client Credentials с текстовым полем Public Key — оно появляется только у пользователей, имеющих роль API.

1. Вставьте содержимое asa-public.pem (с маркерами -----BEGIN PUBLIC KEY----- / -----END PUBLIC KEY-----).

2. Нажмите Generate API Client.

3. Скопируйте три значения, которые покажет Apple: Client ID, Team ID, Key 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 в строке, с экранированием \n, если передается через JSON) поддерживается как альтернатива 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"
      }
    }
  }
}

Аутентификация

Сервер обрабатывает поток OAuth 2.0 client-credentials с использованием утверждения клиента JWT ES256:

1. Подпишите JWT своим закрытым ключом .p8 (заголовок: kid=Key ID, alg=ES256; полезная нагрузка: iss=Team ID, sub=Client ID, aud=https://appleid.apple.com).

2. Отправьте его POST-запросом на https://appleid.apple.com/auth/oauth2/token с параметрами grant_type=client_credentials и scope=searchadsorg.

3. Используйте полученный токен доступа (действует 1 час) с заголовками Authorization: Bearer … и X-AP-Context: orgId=… при каждом вызове API.

Токен кэшируется в памяти примерно за 30 секунд до истечения срока действия, поэтому вы подписываете одно утверждение и обмениваете один токен в час. При получении 401 сервер принудительно обновляет токен и повторяет попытку один раз. При 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. Опрашивайте с помощью custom_reports_get, пока state=COMPLETED. Список через 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. campaigns_create с этим adamId, дневным бюджетом, таргетингом на США, adChannelType=SEARCH, supplySources=["APPSTORE_SEARCH_RESULTS"], billingEvent=TAPS.

4. adgroups_create внутри кампании с defaultBidAmount={amount:"1.00",currency:"USD"} и pricingModel=CPC.

5. targeting_keywords_create с пакетом строк {text, matchType, bidAmount}.

6. cpp_list → выберите productPageId → creatives_create с type=CUSTOM_PRODUCT_PAGE для создания 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 — это только Country / AdminArea / Locality.

• Нет поиска ключевых слов или поиска ключевых слов в рамках группы объявлений по всей организации. Apple ограничивает поиск ключевых слов уровнем кампании (/campaigns/{id}/adgroups/targetingkeywords/find) и суммирует их по группам объявлений; фильтруйте по adGroupId в селекторе для сужения области.

• Нет DELETE для бюджетных заказов. Обновляйте их, не удаляйте.

• Аудитории, прогнозирование, события конверсии НЕ входят в v5 — они находятся в отдельных API Apple (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.