Microsoft Advertising MCP Connector

Servidor MCP True Model B independiente para Custom Connectors de Claude.ai. Un operador puede conectar varias cuentas de Microsoft. Cada conexión puede ver varios clientes y cuentas publicitarias de Microsoft Advertising.

Esto no forma parte del conector Google All-in-One. No tiene dependencia en tiempo de ejecución de ese proyecto, ni colecciones de Firestore compartidas, ni tokens de OAuth compartidos.

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

El sub del JWT de MCP es siempre el operatorId interno. El sub de Microsoft OpenID solo existe en bing_mcp_microsoft_connections.microsoftSubjectId. El correo electrónico es metadatos de visualización, nunca una clave de autorización.

Arquitectura

• App Router de Next.js 15 + mcp-handler Streamable HTTP en /mcp

• MCP OAuth 2.1 con PKCE S256, DCR y Claude CIMD

• Flujo de código de autorización de Microsoft Entra (inquilino common)

• Microsoft Advertising REST v13 (no SOAP)

• Base de datos Firestore con nombre bing-mcp-v1

• Cifrado en reposo del token de actualización con AES-256-GCM

• Cloud Run (sin estado; escucha en $PORT)

Related MCP server: Google Ads MCP Server

Credenciales (son cosas distintas)

Entorno

Copia .env.example a .env. Nunca hagas commit de .env.

Requerido:

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 debe ser bing-mcp-v1. El arranque rechaza (default) y gconnect-mcp-all-v1.

Registro de aplicación de Microsoft Entra

1. Abre Registros de aplicaciones de Microsoft Entra.

2. Crea un registro.

3. Tipos de cuenta compatibles: Cuentas en cualquier directorio de la organización y cuentas personales de Microsoft (para que common funcione).

4. Añade un URI de redirección web: {APP_BASE_URL}/oauth/microsoft/callback (ejemplo local: http://localhost:3000/oauth/microsoft/callback).

5. Crea un secreto de cliente. Guárdalo en MICROSOFT_CLIENT_SECRET.

6. Permisos de API: ámbito delegado de Microsoft Advertising https://ads.microsoft.com/msads.manage. Solicita también openid, profile, email y offline_access.

7. Concede el consentimiento de administrador si tu inquilino lo requiere.

Guías oficiales:

• Autenticación con OAuth

• Solicitar consentimiento del usuario

Token de desarrollador

Obtén un token de desarrollador de Microsoft Advertising desde la configuración de desarrollador de Microsoft Advertising. Los tokens de sandbox se pueden autoemitir; los tokens de producción requieren la aprobación de Microsoft.

Este token es una credencial de aplicación. Se envía como cabecera DeveloperToken en las llamadas REST de Advertising. Nunca se almacena por operador y no debe aparecer jamás en la salida de MCP ni en los registros.

Desarrollo local

npm install
npm test
npm run typecheck
npm run dev

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

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

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

Añade el Custom Connector en Claude.ai apuntando a {APP_BASE_URL}/mcp. Claude completa el OAuth de MCP y, a continuación, el servidor redirige el navegador al inicio de sesión de Microsoft. Tras el consentimiento, continúa de vuelta en Claude.

Firestore en local: o bien Application Default Credentials (gcloud auth application-default login) más FIRESTORE_PROJECT_ID, o bien FIRESTORE_EMULATOR_HOST.

Herramientas MCP (V1, solo lectura)

Conexiones: get_operator, list_microsoft_connections, get_microsoft_connection, start_microsoft_connection, disconnect_microsoft_connection

Clientes / cuentas: list_microsoft_customers, get_microsoft_customer, list_microsoft_accounts, get_microsoft_account

Entidades: list_campaigns, get_campaign, list_ad_groups, get_ad_group, list_ads, get_ad, list_keywords, get_keyword

Informes (API Reporting oficial, envío/sondeo/descarga asíncronos): get_account_performance, get_campaign_performance, get_ad_group_performance, get_keyword_performance

Si la misma cuenta publicitaria es visible a través de más de una conexión de Microsoft, el servidor devuelve un error de ambigüedad y solicita connectionId. Nunca hace suposiciones.

Colecciones de Firestore

Base de datos con nombre: 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

El tráfico entrante de Cloud Run debe ser no autenticado. La autenticación es el JWT de MCP, no Cloud IAM.

La cuenta de servicio de Cloud Run necesita acceso a Firestore en la base de datos con nombre (roles/datastore.user es lo habitual). Usa Application Default Credentials. No hagas commit de un archivo JSON de cuenta de servicio.

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

A continuación, añade {APP_BASE_URL}/oauth/microsoft/callback a la aplicación de Entra y añade el Custom Connector de Claude en {APP_BASE_URL}/mcp.

El tiempo de espera del servicio es de 300 segundos para que los informes asíncronos puedan completarse.

Seguridad

Nunca se exponen a través de MCP ni en los registros: tokens de acceso, tokens de actualización, secretos de cliente, token de desarrollador, claves de cifrado, códigos de autorización.

La autorización utiliza operatorId + connectionId + identificadores de Microsoft. Los nombres y los correos electrónicos no son identificadores de autorización.

V2 (no implementado)

Creación/actualización/pausa de campañas, escrituras de grupos de anuncios y anuncios, escrituras de palabras clave, actualizaciones de presupuesto.

Pruebas

npm test

Las pruebas automatizadas cubren la identidad JWT de MCP, el estado/intercambio/actualización/invalid_grant de OAuth de Microsoft, el aislamiento de operadores, la multiconexión, la misma identidad de Microsoft entre operadores, el rechazo de cuentas ambiguas, el análisis de los CSV de informes, las reglas de cabeceras y la redacción de secretos.

Las rutas en vivo de Claude, del inicio de sesión de Microsoft y de Cloud Run requieren tu aplicación de Entra, token de desarrollador y proyecto de GCP.