mcp-microsoft-ads

No oficial: no está afiliado a Microsoft, ni respaldado ni soportado por Microsoft. Se trata de un servidor MCP (Model Context Protocol) de terceros para Microsoft Advertising. "MCP" es el protocolo abierto que permite que un asistente de IA (Claude, o cualquier otro cliente MCP) llame a herramientas contra un sistema real; aquí, tu cuenta de Microsoft Ads.

El MCP de Microsoft Ads con prioridad en la seguridad: 47 herramientas que cubren la gestión de campañas, grupos de anuncios, palabras clave, palabras clave negativas, segmentación geográfica, programación de anuncios, extensiones, medios, audiencias y objetivos de conversión, además de informes de rendimiento e investigación de palabras clave con Ad Insight, diseñado para que dar acceso de escritura a un asistente de IA a una cuenta de anuncios en vivo no signifique darle un cheque en blanco.

Por qué "la seguridad es lo primero"

Toda herramienta que muta está desactivada por defecto. Activar las escrituras es una variable de entorno, y aun así cada escritura pasa por la misma puerta de seguridad en capas antes de que una sola llamada llegue a la API de Microsoft:

1. MS_ADS_ENABLE_WRITES=true — sin esto, toda herramienta de escritura se niega a ejecutarse. De fábrica, este es un servidor de solo lectura.

2. Borrador → confirmación. Una herramienta de escritura nunca muta en su propia llamada. Devuelve una vista previa (un draft_id y exactamente qué cambiaría); nada se aplica hasta que tú — o tu cliente MCP — llames a confirm_and_apply(draft_id).

3. Límites de gasto. Tanto la creación del borrador como la aplicación rechazan cantidades por encima de MS_ADS_MAX_DAILY_BUDGET (por defecto 1000) o MS_ADS_MAX_CPC (por defecto 50), en la moneda de la propia cuenta, no en USD.

4. Protecciones de cierre seguro para Smart Bidding. Las escrituras de ofertas/ajustes están en una lista blanca de estrategias de oferta manuales (ManualCpc, EnhancedCpc, ManualCpv, ManualCpm, ManualCpa); una estrategia no reconocida o automatizada (MaxConversions, TargetCpa, TargetRoas, …) se rechaza en lugar de asumirse como segura.

5. Registro de auditoría JSONL. Cada borrador y cada aplicación se añaden a un archivo JSONL local de solo anexión: un rastro en texto plano de lo que este servidor realmente hizo.

Respaldado por más de 380 pruebas fuera de línea (sin llamadas a la API en vivo) que ejercitan las protecciones, las peculiaridades del cableado SOAP y el ciclo de vida de borrador/confirmación contra simulaciones.

Sé honesto sobre lo que "borrador → confirmación" no es

Borrador → confirmación es una puerta de vista previa contra accidentes de una sola llamada: un error tipográfico en una oferta, un error de copiar y pegar, llamar a la herramienta equivocada. No es un control de acceso con aprobación humana: el mismo cliente MCP que creó el borrador puede llamar a confirm_and_apply inmediatamente después, sin que el servidor requiera un humano en el bucle. Si quieres que un humano revise cada escritura, eso debe imponerlo tu propio flujo de trabajo (un paso de aprobación separado, un cliente solo para humanos, etc.); este servidor no lo hace por ti.

Una escritura se menciona por separado porque la historia en capas anterior no puede acotarla por completo: apply_recommendation delega en una mutación decidida por Microsoft; solo obtienes una vista previa del ID de la recomendación, no del cambio en sí, por lo que el efecto monetario real no es algo que los límites de gasto de este servidor puedan verificar de antemano. Se mantiene (las recomendaciones de Microsoft pueden ser útiles), se etiqueta claramente como la excepción que es, y está protegida por ambas MS_ADS_ENABLE_WRITES y su propio indicador separado, MS_ADS_ALLOW_APPLY_RECOMMENDATION; así que activar las escrituras en general no activa esta.

Lo que este servidor no hace

• Sin diagnósticos de Quality Score.

• Sin reintentos automáticos/backoff en fallos transitorios de la API (una llamada fallida falla; tú reintentas).

• Construido sobre el SDK SOAP de Bing Ads de Microsoft, que Microsoft ha anunciado como fin de vida: ver más abajo.

Related MCP server: OpenAI Ads MCP

Fin de vida de SOAP y hoja de ruta hacia REST

Este servidor está construido sobre el SDK SOAP bingads. Microsoft ha anunciado que SOAP llegará a su fin de vida el 2027-01-31 y recomienda migrar antes del 2026-10-01 (las nuevas funciones de la API se publicarán solo en REST a partir de entonces). Consulta la guía de Microsoft Migrate to REST API y la guía de migración de SOAP a REST del SDK de Python. Portar las herramientas de este servidor a REST es el elemento de la hoja de ruta; SOAP sigue funcionando hoy y no desaparecerá hasta la fecha de fin de vida, pero no planifiques a largo plazo en torno a él.

Cómo se compara

Comparación verificada por última vez el 2026-08-24. Este proyecto no pretende conocer el conjunto de funciones exacto actual de las otras filas más allá de si son de solo lectura o no; consulta el repositorio/documentación de cada proyecto para obtener detalles. Los diferenciadores anteriores (escrituras opcionales, borrador→confirmación en dos fases, límites de gasto, protecciones de cierre seguro de Smart Bidding, registro de auditoría JSONL, más de 380 pruebas fuera de línea) son en torno a lo que se construye este proyecto.

Instalación

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]"

La configuración completa (registro de la aplicación de Azure, token de desarrollador, primer inicio de sesión con OAuth) está en docs/setup.md. Esta sección solo cubre cómo ejecutar el servidor una vez que ya existen las credenciales.

Credenciales

Las credenciales viven fuera del repositorio, en un archivo YAML (por defecto ~/.mcp-microsoft-ads/credentials.yaml, se puede sobrescribir con MS_ADS_CREDENTIALS_PATH): developer_token, client_id, client_secret, refresh_token, customer_id, account_id, tenant.

Los seis campos estáticos (todo excepto refresh_token) se pueden configurar en su lugar como variables de entorno MS_ADS_DEVELOPER_TOKEN, MS_ADS_CLIENT_ID, MS_ADS_CLIENT_SECRET, MS_ADS_CUSTOMER_ID, MS_ADS_ACCOUNT_ID, MS_ADS_TENANT; el entorno gana sobre el archivo cuando ambos están presentes. refresh_token es solo de archivo: Microsoft lo rota en cada uso, y un token rotado debe persistirse en algún lugar para la siguiente ejecución, lo que una variable de entorno no puede hacer. El servidor persiste cada rotación de vuelta al archivo de credenciales de forma atómica (se conserva un .bak).

Recorrido de primera ejecución

1. Inicio de sesión de arranque:

   .venv/bin/python -m mcp_microsoft_ads.reauth

   Realiza un inicio de sesión OAuth interactivo en tu navegador y escribe el refresh_token resultante en el archivo de credenciales. Consulta docs/setup.md para el registro de la aplicación de Azure y el token de desarrollador de los que depende este paso.

2. Inicia el servidor en modo de solo lectura (aún no configures MS_ADS_ENABLE_WRITES) y, desde tu cliente MCP, llama a health_check, luego a list_accounts y/o get_account_info.

3. Confirma que la cuenta es la que quieres: verifica el ID de cuenta, el nombre de cuenta y la moneda de cuenta devueltos por esas llamadas contra la cuenta a la que pretendes permitir que este servidor acceda. Los límites de gasto siguientes se aplican en la moneda de esa cuenta, por lo que vale la pena detectar una discrepancia de moneda antes de que las escrituras estén activadas.

4. Solo entonces configura MS_ADS_ENABLE_WRITES=true (y, si lo deseas, MS_ADS_ALLOW_APPLY_RECOMMENDATION=true) y reinicia el servidor.

Configuración del cliente MCP

Ambas configuraciones asumen que el venv anterior vive en ~/mcp-microsoft-ads/.venv; reemplázalo con la ruta absoluta real en tu máquina (ambos clientes necesitan una ruta absoluta, no ~).

Claude Code (.mcp.json en tu proyecto, o mediante 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"]
    }
  }
}

No apuntes dos clientes concurrentes al mismo archivo de credenciales

Compartir un archivo de credenciales entre clientes concurrentes no es compatible. El refresh_token es un archivo mutable, rotatorio y compartido: cada actualización genera un token nuevo e invalida inmediatamente el anterior, y la operación de lectura-modificación-escritura que persiste la rotación no se puede serializar de forma segura entre dos procesos separados en esta capa. Dos clientes que compiten por actualizar desde el mismo archivo pueden dejarse mutuamente con un token invalidado. Si quieres más de un cliente concurrente (por ejemplo, Claude Code y Claude Desktop abiertos a la vez), dale a cada uno su propio archivo de credenciales y su propio registro de aplicación de Azure: configura MS_ADS_CREDENTIALS_PATH de forma diferente por cliente y arranca cada uno con su propia ejecución de reauth.

Variables de entorno

Nota sobre la moneda: MS_ADS_MAX_DAILY_BUDGET y MS_ADS_MAX_CPC se comparan directamente con los montos en la moneda propia de la cuenta, no se convierten a o desde USD. Un tope de 1000 significa 1000 unidades de la moneda en la que esté denominada la cuenta.

Pruebas / lint

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

Documentación

• docs/setup.md — Registro de la aplicación de Azure, token de desarrollador, arranque completo.

• SECURITY.md — cómo reportar una vulnerabilidad.

• CHANGELOG.md — historial de versiones.

Licencia y soporte

Con licencia MIT — consulte LICENSE. Este es un proyecto de código abierto sin fines de lucro y de mejor esfuerzo: sin SLA, sin tiempo de respuesta garantizado. Los problemas se supervisan y se clasifican de la mejor manera posible.