Microsoft Advertising MCP Connector

Автономный True Model B MCP-сервер для Custom Connectors в Claude.ai. Один оператор может подключить несколько учетных записей Microsoft. Каждое подключение может видеть несколько клиентов Microsoft Advertising и рекламных аккаунтов.

Это не часть коннектора Google All-in-One. У него нет зависимости от этого проекта во время выполнения, нет общих коллекций Firestore и общих токенов OAuth.

Claude.ai
   │  MCP OAuth 2.1
   ▼
operatorId
   ├── Microsoft Connection A → customers → advertising accounts → campaigns / reports
   ├── Microsoft Connection B
   └── Microsoft Connection C

MCP JWT sub — это всегда внутренний operatorId. Microsoft OpenID sub хранится только в bing_mcp_microsoft_connections.microsoftSubjectId. Электронная почта — это отображаемые метаданные, а не ключ авторизации.

Архитектура

• Next.js 15 App Router + mcp-handler Streamable HTTP на /mcp

• MCP OAuth 2.1 с PKCE S256, DCR и Claude CIMD

• Поток авторизации Microsoft Entra (код авторизации, тенант common)

• Microsoft Advertising REST v13 (не SOAP)

• Именованная база данных Firestore bing-mcp-v1

• Шифрование refresh-токенов AES-256-GCM при хранении

• Cloud Run (без состояния; прослушивание на $PORT)

Related MCP server: Google Ads MCP Server

Учетные данные (это разные вещи)

Окружение

Скопируйте .env.example в .env. Никогда не коммитьте .env.

Обязательные:

APP_BASE_URL
MICROSOFT_CLIENT_ID
MICROSOFT_CLIENT_SECRET
MICROSOFT_REDIRECT_URI
MICROSOFT_ADS_DEVELOPER_TOKEN
MCP_TOKEN_SECRET
OAUTH_STATE_SECRET
TOKEN_ENCRYPTION_KEY
FIRESTORE_PROJECT_ID
FIRESTORE_DATABASE_ID=bing-mcp-v1

FIRESTORE_DATABASE_ID должен быть bing-mcp-v1. При запуске отклоняются (default) и gconnect-mcp-all-v1.

Регистрация приложения Microsoft Entra

1. Откройте Регистрация приложений Microsoft Entra.

2. Создайте регистрацию.

3. Поддерживаемые типы учетных записей: Учетные записи в любом organizational directory и личные учетные записи Microsoft (чтобы работал common).

4. Добавьте URI перенаправления Web: {APP_BASE_URL}/oauth/microsoft/callback (локальный пример: http://localhost:3000/oauth/microsoft/callback).

5. Создайте секрет клиента. Сохраните его в MICROSOFT_CLIENT_SECRET.

6. Разрешения API: делегированная область Microsoft Advertising https://ads.microsoft.com/msads.manage. Также запросите openid, profile, email и offline_access.

7. Предоставьте согласие администратора, если этого требует ваш тенант.

Официальные руководства:

• Аутентификация с OAuth

• Запрос согласия пользователя

Токен разработчика

Получите токен разработчика Microsoft Advertising в настройках разработчика Microsoft Advertising. Песочные токены можно выпускать самостоятельно; производственные токены требуют одобрения Microsoft.

Этот токен — учетные данные приложения. Он отправляется как заголовок DeveloperToken в вызовах Advertising REST. Он никогда не хранится для каждого оператора и не должен появляться в выводе MCP или в журналах.

Локальная разработка

npm install
npm test
npm run typecheck
npm run dev

• Health: GET http://localhost:3000/health

• MCP: http://localhost:3000/mcp

• Callback Microsoft: http://localhost:3000/oauth/microsoft/callback

Добавьте Custom Connector в Claude.ai, указав {APP_BASE_URL}/mcp. Claude завершает MCP OAuth, затем сервер перенаправляет браузер на вход в Microsoft. После согласия вернитесь в Claude.

Firestore локально: либо Application Default Credentials (gcloud auth application-default login) плюс FIRESTORE_PROJECT_ID, либо FIRESTORE_EMULATOR_HOST.

Инструменты MCP (V1, только чтение)

Подключения: get_operator, list_microsoft_connections, get_microsoft_connection, start_microsoft_connection, disconnect_microsoft_connection

Клиенты / аккаунты: list_microsoft_customers, get_microsoft_customer, list_microsoft_accounts, get_microsoft_account

Сущности: list_campaigns, get_campaign, list_ad_groups, get_ad_group, list_ads, get_ad, list_keywords, get_keyword

Отчеты (официальный Reporting API, асинхронная отправка/опрос/загрузка): get_account_performance, get_campaign_performance, get_ad_group_performance, get_keyword_performance

Если один и тот же рекламный аккаунт виден через несколько подключений Microsoft, сервер возвращает ошибку неоднозначности и запрашивает connectionId. Он никогда не угадывает.

Коллекции Firestore

Именованная база данных: bing-mcp-v1

• bing_mcp_operators

• bing_mcp_microsoft_connections

• bing_mcp_connection_uniques ({operatorId}_{microsoftSubjectId})

• bing_mcp_microsoft_customers

• bing_mcp_microsoft_accounts

• bing_mcp_oauth_transactions

• bing_mcp_sessions

Cloud Run

Входящий трафик Cloud Run должен быть без аутентификации. Аутентификация — это MCP JWT, а не Cloud IAM.

Сервисный аккаунт Cloud Run должен иметь доступ к Firestore в именованной базе данных (обычно roles/datastore.user). Используйте Application Default Credentials. Не коммитьте JSON-файл сервисного аккаунта.

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-set-env.ps1 -ProjectId YOUR_PROJECT -AppBaseUrl https://... -MicrosoftClientId ... -MicrosoftClientSecret ... -McpTokenSecret ... -OauthStateSecret ... -TokenEncryptionKey ... -MicrosoftAdsDeveloperToken ...

Затем добавьте {APP_BASE_URL}/oauth/microsoft/callback в приложение Entra и добавьте Custom Connector Claude по адресу {APP_BASE_URL}/mcp.

Таймаут сервиса — 300 секунд, чтобы асинхронные отчеты могли завершиться.

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

Никогда не раскрываются через MCP или журналы: токены доступа, refresh-токены, секреты клиента, токен разработчика, ключи шифрования, коды авторизации.

Авторизация использует operatorId + connectionId + идентификаторы Microsoft. Имена и адреса электронной почты не являются идентификаторами авторизации.

V2 (не реализовано)

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

Тесты

npm test

Автоматические тесты покрывают идентификацию MCP JWT, состояние/обмен/обновление/invalid_grant OAuth Microsoft, изоляцию операторов, множественные подключения, одну и ту же личность Microsoft у разных операторов, отклонение неоднозначных аккаунтов, разбор CSV-отчетов, правила заголовков и редактирование секретов.

Живые пути Claude, входа в Microsoft и Cloud Run требуют вашего приложения Entra, токена разработчика и проекта GCP.