Apple Ads MCP

Локальный Model Context Protocol сервер для Apple Ads Platform API v1. Он предоставляет Codex, Claude и другим MCP-клиентам типизированные инструменты для исследования рекламы в App Store, составления отчётов, аудита и управления кампаниями с подтверждением через квитанции.

Apple Ads MCP — независимое программное обеспечение с открытым исходным кодом. Оно не связано с Apple Inc., не одобрено и не спонсируется ею. Apple Ads и App Store являются товарными знаками Apple Inc.

Зачем нужен Apple Ads MCP

• Инструменты, ориентированные на агентов: поиск собственных приложений, исследование ключевых слов, просмотр отчётов, аудит кампаний и подготовка узконаправленных изменений.

• Локальные учётные данные: закрытый ключ остаётся на вашем устройстве; OAuth-токены и операционные квитанции хранятся только в памяти процесса.

• Только чтение по умолчанию: исследование и отчёты работают без включения изменений.

• Явная маршрутизация аккаунтов: каждый инструмент, работающий с аккаунтом, требует профиль и adAccountId.

• Безопасные изменения: каждая запись требует предварительного просмотра, одноразовой квитанции на десять минут и повторной проверки текущего состояния.

• Ограниченный вывод: структурированный MCP-контент, ограниченные массивы, пагинация, метаданные о лимитах и структурированные ошибки Apple.

• Портативный рантайм: один бинарный файл Go для macOS, Linux и Windows, а также OCI-образ.

Related MCP server: OpenAI Ads MCP

Статус релиза

v0.1.0 — первый публичный релиз. Полный локальный набор тестов, детектор гонок, статический анализ, сканирование уязвимостей, сканирование секретов, проверка дистрибутивов и реальные MCP stdio-тесты проходят успешно.

Частное живое приёмочное тестирование на управляемом оператором аккаунте Apple Ads подтвердило:

• OAuth, обнаружение аккаунтов, поиск организаций и собственных приложений;

• доступность витрин, предложения ключевых слов, популярность и ограниченные отчёты;

• предпросмотр → квитанция → применение → прямое чтение через API;

• создание приостановленных кампаний, групп объявлений, таргетированных и минус-ключевых слов;

• отклонение при расхождении состояния, одноразовые квитанции, восстановление режима только чтения и нулевые расходы на рекламу.

В этом репозитории не хранятся учётные данные, экспорт аккаунтов, приватные данные кампаний или живые квитанции.

Возможности

Инструменты чтения

Инструменты записи с подтверждением через квитанции

• Создание и обновление кампаний, групп объявлений, таргетированных и минус-ключевых слов.

• Использование предварительных основ для объявлений и креативов App Store в зависимости от источника; поддержка зависит от комбинации размещения Apple и страницы продукта.

• Предпросмотр приостановки/возобновления кампаний, ставок групп объявлений и ограничений CPA.

• Применение ровно одного предпросмотра через operations_apply.

• Проверка или верификация неоднозначной операции через 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 всё ещё соответствует состоянию, прочитанному во время предпросмотра.

Квитанции истекают через десять минут и являются одноразовыми. Изменения никогда не повторяются после неоднозначного сбоя транспорта. Сервер возвращает committed_unverified и требует прямой проверки состояния перед любой последующей записью.

Для обычного исследования и отчётов запускайте сервер без --allow-writes и держите все профили с allowWrites: false.

Установка

GitHub Releases

Скачайте архив для вашей платформы с GitHub Releases. Каждый релиз включает контрольные суммы SHA-256 и SPDX SBOM.

Пример для Apple silicon:

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 запишите несекретные client ID, team ID и key ID, показанные в интерфейсе Apple Ads.

Настройка

Создайте профиль в интерактивном режиме:

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

Общая конфигурация MCP для Codex, Claude Desktop или другого stdio-клиента:

{
  "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. Навык направляет онбординг, исследование, рабочие процессы кампаний и безопасность изменений, не помещая учётные данные в подсказки.

Включение записи для одной сессии

Держите allowWrites: false в постоянном профиле, когда это возможно. Для явно авторизованной сессии обслуживания временно включите оба ограничителя:

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

ACL Apple, явный profile, явный adAccountId, предпросмотр, привязка квитанции, срок действия и проверки расхождений по-прежнему применяются. Запуск сервера с включёнными ограничителями записи сам по себе ничего не меняет.

Известное поведение платформы

• У Apple Ads нет публичной песочницы. Автоматический живой CI — по желанию и строго только для чтения.

• Доступность, предложения, популярность, рекомендации и отчёты зависят от аккаунта, приложения, витрины и истории кампаний.

• Холодные аккаунты могут не возвращать рекомендаций по целевой CPA или бюджету.

• Apple может возвращать ошибки валидации или серверные ошибки, специфичные для конечной точки. MCP сохраняет ограниченные безопасные детали для ответов 4xx и скрывает повторяемые серверные ошибки.

• Во время живого приёмочного тестирования Apple отклонила отдельный объект Ad для источника APPSTORE_SEARCH_RESULTS. В результатах поиска использовалась опубликованная страница продукта по умолчанию.

• Названия кампаний проверяются Apple; некоторые знаки препинания, принимаемые веб-интерфейсом, могут быть отклонены API.

• Отчёты о производительности остаются пустыми, пока нет данных о доставке. Атрибуция от установки до подписки или пробного периода относится к вашему стеку атрибуции, а не к этому API.

• Полное покрытие конформности MCP от upstream остаётся в ожидании, поскольку текущий раннер принимает URL сервера, но не может запустить дочерний процесс stdio. Этот репозиторий тестирует реальную stdio-сессию через официальный Go SDK.

Разработка

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, дорожную карту и машиночитаемую матрицу операций.

Артефакты релиза

Каждый тегированный релиз публикует:

• архивы для macOS, Linux и Windows для AMD64 и ARM64, где поддерживается;

• checksums.txt с SHA-256 дайджестами;

• SPDX-спецификации программного обеспечения, сгенерированные с помощью Syft;

• формулу Homebrew с закреплённой контрольной суммой;

• многоархитектурные OCI-образы для Linux AMD64 и ARM64;

• метаданные пакета MCP Registry.

Лицензия

MIT