apple-search-ads-mcp

Name: Apple Ads MCP
Author: AppVisionOS

Сервер протокола контекста модели (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

Настройка

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.

Вставьте содержимое asa-public.pem (с маркерами -----BEGIN PUBLIC KEY----- / -----END PUBLIC KEY-----).
Нажмите Generate API Client.
Скопируйте три значения, которые покажет 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:

Подпишите JWT своим закрытым ключом .p8 (заголовок: kid=Key ID, alg=ES256; полезная нагрузка: iss=Team ID, sub=Client ID, aud=https://appleid.apple.com).
Отправьте его POST-запросом на https://appleid.apple.com/auth/oauth2/token с параметрами grant_type=client_credentials и scope=searchadsorg.
Используйте полученный токен доступа (действует 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)

Инструмент	Эндпоинт
`reports_campaigns`	`POST /reports/campaigns`
`reports_adgroups`	`POST /reports/campaigns/{id}/adgroups`
`reports_keywords_in_campaign`	`POST /reports/campaigns/{id}/keywords`
`reports_keywords_in_adgroup`	`POST /reports/campaigns/{id}/adgroups/{id}/keywords`
`reports_search_terms_in_campaign`	`POST /reports/campaigns/{id}/searchterms`
`reports_search_terms_in_adgroup`	`POST /reports/campaigns/{id}/adgroups/{id}/searchterms`
`reports_ads_in_campaign`	`POST /reports/campaigns/{id}/ads`

Все принимают 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:

org_acls → выберите orgId.
search_apps для вашего приложения → получите adamId.
campaigns_create с этим adamId, дневным бюджетом, таргетингом на США, adChannelType=SEARCH, supplySources=["APPSTORE_SEARCH_RESULTS"], billingEvent=TAPS.
adgroups_create внутри кампании с defaultBidAmount={amount:"1.00",currency:"USD"} и pricingModel=CPC.
targeting_keywords_create с пакетом строк {text, matchType, bidAmount}.
cpp_list → выберите productPageId → creatives_create с type=CUSTOM_PRODUCT_PAGE для создания creativeId → ads_create для привязки к группе объявлений.
Подождите несколько дней. reports_campaigns для общих показателей, затем reports_search_terms_in_campaign для сбора новых ключевых слов / минус-слов.
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.

Apple Ads MCP