aapl-ads-mcp

MCP-сервер, который подключает Claude (и любой MCP-совместимый клиент) к Apple Search Ads API v5.

Что это такое

MCP (Model Context Protocol) — это открытый стандарт, позволяющий ИИ-ассистентам вызывать внешние инструменты. Этот сервер реализует транспорт MCP stdio и предоставляет 9 инструментов «только для чтения», которые запрашивают данные вашего аккаунта Apple Search Ads: кампании, группы объявлений, ключевые слова и отчеты об эффективности.

Вы устанавливаете его один раз, указываете на него в Claude Desktop, а затем задаете вопросы на обычном языке: «Какие ключевые слова принесли больше всего установок в прошлом месяце?» или «Покажи мне кампании с нулевым количеством показов на этой неделе».

Related MCP server: tiktok-ads-mcp

Зачем это нужно

Официальные панели управления ASA хороши для людей, но не подходят для ситуативного анализа или автоматизированной отчетности. Существующие альтернативы MCP либо являются SaaS-решениями (вы передаете свои ключи), либо не поддерживаются. Это self-hosted решение с открытым исходным кодом, которое вы полностью контролируете.

Функции

• 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.

Ограничения

• Только для чтения. В этом релизе нет операций записи (создание, обновление, приостановка).

• Требуется доступ к API управления кампаниями Apple Search Ads. Вам необходимо создать API-пользователя в своем аккаунте ASA и сгенерировать пару ключей ES256.

• Агрегированные метрики установок работают без интеграции на стороне приложения. Поля tapInstalls, viewInstalls и связанные с ними поля в отчетах ASA заполняются непосредственно 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. Создание API-пользователя в Apple Search Ads

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. Найдите свой org_id в Account Settings → Overview

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 дней

Какие ключевые слова принесли установки в моей кампании Brand на прошлой неделе?

Какие поисковые запросы активировали мои объявления в прошлом месяце? Сосредоточься на тех, у которых есть показы, но нет установок.

Сравни еженедельные расходы по всем кампаниям за 1 квартал 2025 года

Покажи группы объявлений в кампании 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 перед подключением.

Pre-commit хуки

Установите хуки lefthook локально после клонирования:

npx lefthook install

Это настраивает:

• gitleaks protect --staged — блокирует коммиты, содержащие секреты

• Проверку линтинга Biome для подготовленных (staged) .ts файлов

• Проверку типов TypeScript

Участие в разработке

См. docs/ARCHITECTURE.md для получения технических подробностей: поток аутентификации, дизайн HTTP-клиента, паттерн инструментов, особенности схемы отчетов и уроки, извлеченные из ASA v5 во время разработки.

Отчеты об ошибках и пулл-реквесты приветствуются.

Безопасность

• Никогда не коммитьте файлы .env или *.pem — оба типа файлов добавлены в .gitignore

• Храните private-key.pem вне корня репозитория

• Токен доступа хранится только в оперативной памяти и никогда не записывается на диск

• Если вы подозреваете, что ключ был скомпрометирован, обновите его в ASA → Account Settings → API

Лицензия

MIT — см. LICENSE.