mcp-microsoft-ads

Неофициальный — не связан с Microsoft, не одобрен и не поддерживается Microsoft. Это сторонний MCP-сервер (Model Context Protocol) для Microsoft Advertising. «MCP» — это открытый протокол, который позволяет ИИ-ассистенту (Claude или любому другому MCP-клиенту) вызывать инструменты для работы с реальной системой — здесь, с вашим аккаунтом Microsoft Ads.

MCP-сервер для Microsoft Ads с приоритетом безопасности: 47 инструментов, покрывающих управление кампаниями, группами объявлений, ключевыми словами, минус-словами, геотаргетингом, расписанием показов, расширениями, медиа, аудиториями и целями конверсий, а также отчёты по эффективности и исследование ключевых слов Ad Insight — создан так, чтобы предоставление ИИ-ассистенту доступа на запись к живому рекламному аккаунту не означало предоставление ему «пустого чека».

Почему «безопасность прежде всего»

Каждый изменяющий инструмент по умолчанию отключён. Включение записи — это одна переменная окружения, и даже тогда каждая запись проходит через один и тот же многоуровневый контроль, прежде чем хотя бы один вызов достигнет API Microsoft:

1. MS_ADS_ENABLE_WRITES=true — без этого каждый инструмент записи отказывается работать. Из коробки это сервер только для чтения.

2. Черновик → подтверждение. Инструмент записи никогда не изменяет данные при собственном вызове. Он возвращает предпросмотр (draft_id и точное описание того, что изменится); ничего не применяется, пока вы — или ваш MCP-клиент — не вызовете confirm_and_apply(draft_id).

3. Лимиты расходов. Создание черновика и применение отклоняют суммы выше MS_ADS_MAX_DAILY_BUDGET (по умолчанию 1000) или MS_ADS_MAX_CPC (по умолчанию 50), в валюте самого аккаунта, а не в долларах США.

4. Защита от сбоев при интеллектуальных ставках. Запись ставок и корректировок разрешена только для стратегий ручных ставок (ManualCpc, EnhancedCpc, ManualCpv, ManualCpm, ManualCpa); неизвестная или автоматизированная стратегия (MaxConversions, TargetCpa, TargetRoas, …) отклоняется, а не считается безопасной.

5. Журнал аудита JSONL. Каждый черновик и каждое применение добавляются в локальный, доступный только для добавления файл JSONL — текстовый след того, что этот сервер фактически сделал.

Подкреплено 380+ офлайн-тестами (без живых вызовов API), которые проверяют ограничения, особенности SOAP-соединения и жизненный цикл черновик/подтверждение на фейковых объектах.

Будьте честны насчёт того, чем «черновик → подтверждение» не является

Черновик → подтверждение — это предварительный контроль от случайных ошибок при одиночном вызове — опечатка в ставке, ошибка копирования, вызов не того инструмента. Это не контроль доступа с одобрением человека: тот же MCP-клиент, который создал черновик, может немедленно вызвать confirm_and_apply, и сервер не требует участия человека. Если вы хотите, чтобы каждую запись проверял человек, это должно обеспечиваться вашим собственным рабочим процессом (отдельный шаг одобрения, клиент только для людей и т. д.) — этот сервер не делает это за вас.

Одна операция записи выделена отдельно, потому что многоуровневая схема выше не может полностью её ограничить: apply_recommendation передаёт управление изменению, определяемому Microsoft — вы видите только идентификатор рекомендации, а не само изменение, поэтому фактический денежный эффект не может быть проверен лимитами расходов этого сервера заранее. Она сохранена (рекомендации Microsoft могут быть полезны), явно помечена как исключение и ограничена обоими флагами: MS_ADS_ENABLE_WRITES и отдельным флагом MS_ADS_ALLOW_APPLY_RECOMMENDATION — так что общее включение записи не включает эту операцию.

Что этот сервер не делает

• Нет диагностики Quality Score.

• Нет автоматических повторов/откатов при временных сбоях API (неудачный вызов — это неудача; вы повторяете).

• Построен на SOAP-пакете Bing Ads SDK от Microsoft, который Microsoft объявила устаревшим — см. ниже.

Related MCP server: OpenAI Ads MCP

Конец поддержки SOAP и дорожная карта REST

Этот сервер построен на SOAP SDK bingads. Microsoft объявила, что SOAP прекращает поддержку 2027-01-31, и рекомендует мигрировать до 2026-10-01 (с этого момента новые функции API будут только в REST). См. руководство Microsoft Migrate to REST API и руководство по миграции Python SDK с SOAP на REST. Перенос инструментов этого сервера на REST — пункт дорожной карты; SOAP всё ещё работает сегодня и не исчезнет до даты окончания поддержки, но не планируйте долгосрочную работу на нём.

Сравнение

Сравнение проверено 2026-08-24. Этот проект не претендует на знание точного текущего набора функций других строк, кроме того, что они только для чтения или нет — проверяйте репозитории/документацию каждого проекта для деталей. Отличия выше (запись по выбору, двухфазный черновик→подтверждение, лимиты расходов, защита Smart Bidding от сбоев, журнал аудита JSONL, 380+ офлайн-тестов) — это то, вокруг чего построен этот проект.

Установка

git clone https://github.com/wvuhskr/mcp-microsoft-ads.git
cd mcp-microsoft-ads
python3 -m venv .venv  # requires Python >= 3.12
.venv/bin/pip install -e ".[dev]"

Полная настройка — регистрация приложения Azure, токен разработчика, первый вход через OAuth — описана в docs/setup.md. Этот раздел охватывает только запуск сервера, когда учётные данные уже существуют.

Учётные данные

Учётные данные хранятся вне репозитория, в YAML-файле (по умолчанию ~/.mcp-microsoft-ads/credentials.yaml, переопределяется через MS_ADS_CREDENTIALS_PATH): developer_token, client_id, client_secret, refresh_token, customer_id, account_id, tenant.

Шесть статических полей (всё, кроме refresh_token) можно также задать через переменные окружения MS_ADS_DEVELOPER_TOKEN, MS_ADS_CLIENT_ID, MS_ADS_CLIENT_SECRET, MS_ADS_CUSTOMER_ID, MS_ADS_ACCOUNT_ID, MS_ADS_TENANT — переменные окружения имеют приоритет над файлом, когда присутствуют оба. refresh_token хранится только в файле: Microsoft ротирует его при каждом использовании, и ротированный токен должен быть сохранён где-то для следующего запуска, что переменная окружения не может сделать. Сервер атомарно сохраняет каждую ротацию обратно в файл учётных данных (сохраняется .bak).

Пошаговое руководство для первого запуска

1. Начальный вход:

   .venv/bin/python -m mcp_microsoft_ads.reauth

   Проводит интерактивный вход через OAuth в вашем браузере и записывает полученный refresh_token в файл учётных данных. См. docs/setup.md для регистрации приложения Azure и токена разработчика, от которых зависит этот шаг.

2. Запустите сервер в режиме только для чтения (не устанавливайте MS_ADS_ENABLE_WRITES пока) и из вашего MCP-клиента вызовите health_check, затем list_accounts и/или get_account_info.

3. Убедитесь, что аккаунт тот, который вы имеете в виду — проверьте идентификатор аккаунта, имя аккаунта и валюту аккаунта, возвращённые этими вызовами, против аккаунта, которому вы собираетесь разрешить доступ этому серверу. Лимиты расходов ниже применяются в валюте этого аккаунта, поэтому несоответствие валюты стоит выявить до включения записи.

4. Только после этого установите MS_ADS_ENABLE_WRITES=true (и, если хотите, MS_ADS_ALLOW_APPLY_RECOMMENDATION=true) и перезапустите сервер.

Конфигурация MCP-клиента

Обе конфигурации предполагают, что виртуальное окружение находится по пути ~/mcp-microsoft-ads/.venv — замените его на фактический абсолютный путь на вашей машине (обоим клиентам нужен абсолютный путь, а не ~).

Claude Code (.mcp.json в вашем проекте или через claude mcp add):

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

Не направляйте два одновременных клиента на один и тот же файл учётных данных

Совместное использование одного файла учётных данных между одновременными клиентами не поддерживается. refresh_token — это ротируемый, общий, изменяемый файл: каждое обновление создаёт новый токен и немедленно аннулирует старый, а операция чтение-изменение-запись, которая сохраняет ротацию, не может быть безопасно сериализована между двумя отдельными процессами на этом уровне. Два клиента, соревнующихся за обновление из одного файла, могут оставить друг друга с аннулированным токеном. Если вам нужно более одного одновременного клиента (например, Claude Code и Claude Desktop открыты одновременно), дайте каждому свой собственный файл учётных данных и свою собственную регистрацию приложения Azure — установите MS_ADS_CREDENTIALS_PATH отдельно для каждого клиента и выполните начальный вход с помощью собственного запуска reauth.

Переменные окружения

Примечание о валюте: MS_ADS_MAX_DAILY_BUDGET и MS_ADS_MAX_CPC сравниваются напрямую с суммами в собственной валюте аккаунта, а не конвертируются в USD или из USD. Предел 1000 означает 1000 единиц той валюты, в которой номинирован аккаунт.

Тест / lint

.venv/bin/python -m pytest -q     # offline test suite, ~370 tests, no live API calls
.venv/bin/python -m ruff check .  # lint

Документация

• docs/setup.md — регистрация приложения Azure, токен разработчика, полная настройка.

• SECURITY.md — как сообщить об уязвимости.

• CHANGELOG.md — история релизов.

Лицензия и поддержка

Лицензия MIT — см. LICENSE. Это проект с открытым исходным кодом, поддерживаемый на добровольной основе, без оплаты: без SLA, без гарантированного времени ответа. Проблемы отслеживаются и обрабатываются по мере возможности.