Anuncios meta MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con la API de Meta Ads. Esta herramienta permite a los modelos de IA acceder, analizar y gestionar campañas publicitarias de Meta a través de una interfaz estandarizada, lo que permite a los LLM recuperar datos de rendimiento, visualizar creatividades publicitarias y proporcionar información estratégica para Facebook, Instagram y otras plataformas de Meta.

AVISO LEGAL: Esta es una herramienta de terceros no oficial y no está asociada, respaldada ni afiliada a Meta de ninguna manera. Este proyecto se mantiene de forma independiente y utiliza las API públicas de Meta de acuerdo con sus términos de servicio. Meta, Facebook, Instagram y otras marcas de Meta son marcas registradas de sus respectivos propietarios.

Captura de pantalla: uso de un LLM para comprender el rendimiento de su anuncio.

Características

• Análisis de campañas impulsado por IA : deje que su LLM favorito analice sus campañas y proporcione información útil sobre el rendimiento.
• Recomendaciones estratégicas : reciba sugerencias respaldadas por datos para optimizar el gasto en publicidad, la segmentación y el contenido creativo.
• Monitoreo automatizado : Solicite a cualquier LLM compatible con MCP que realice un seguimiento de las métricas de rendimiento y le avise sobre cambios significativos
• Optimización del presupuesto : obtenga recomendaciones para reasignar el presupuesto a conjuntos de anuncios con mejor rendimiento
• Mejora creativa : reciba comentarios sobre el texto del anuncio, las imágenes y las llamadas a la acción.
• Gestión de campañas : solicitar cambios en campañas, conjuntos de anuncios y anuncios (todos los cambios requieren confirmación explícita)
• Integración multiplataforma : funciona con Facebook, Instagram y todas las plataformas de anuncios meta.
• Compatibilidad universal con LLM : compatible con cualquier cliente MCP, incluidos Claude Desktop, Cursor, Cherry Studio y más
• Autenticación simple : configuración sencilla con autenticación OAuth segura
• Compatibilidad multiplataforma : funciona en Windows, macOS y Linux

Instalación

Uso de uv (recomendado)

Al usar uv, no se requiere una instalación específica. Podemos usar uvx para ejecutar directamente meta-ads-mcp:

Si desea instalar el paquete:

Para el desarrollo (si ha clonado el repositorio):

Usando pip

Alternativamente, puede instalar meta-ads-mcp a través de pip:

Después de la instalación, puedes ejecutarlo como:

Configuración

Inicio rápido con la autenticación de Pipeboard (recomendado)

La forma más sencilla de configurar Meta Ads MCP es mediante la autenticación de Pipeboard:

1. Regístrate en Pipeboard.co y genera un token API. Obtén tu token gratuito en https://pipeboard.co
2. Establezca la variable de entorno:
   export PIPEBOARD_API_TOKEN=your_pipeboard_token # Token obtainable via https://pipeboard.co
3. Ejecute meta-ads-mcp sin necesidad de configurar una aplicación Meta Developer:
   uvx meta-ads-mcp

Este método proporciona tokens de mayor duración (60 días), configuración simplificada y renovación automática de tokens.

Uso con Cursor o Claude Desktop

Agregue esto a su claude_desktop_config.json para integrar con Claude o ~/.cursor/mcp.json para integrar con Cursor:

O si prefieres la autenticación Meta directa (usando tu propia aplicación de Facebook):

Herramientas MCP disponibles

1. mcp_meta_ads_get_ad_accounts
   • Obtener cuentas de anuncios accesibles para un usuario
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • user_id : ID de usuario meta o "yo" para el usuario actual
     • limit : Número máximo de cuentas a devolver (predeterminado: 10)
   • Devoluciones: Lista de cuentas publicitarias accesibles con sus detalles
2. mcp_meta_ads_get_account_info
   • Obtenga información detallada sobre una cuenta publicitaria específica
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
   • Devuelve: Información detallada sobre la cuenta especificada
3. mcp_meta_ads_get_campaigns
   • Obtenga campañas para una cuenta de Meta Ads con filtrado opcional
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
     • limit : Número máximo de campañas a devolver (predeterminado: 10)
     • status_filter : Filtrar por estado (vacío para todos, o 'ACTIVO', 'PAUSADO', etc.)
   • Devoluciones: Lista de campañas que coinciden con los criterios
4. mcp_meta_ads_get_campaign_details
   • Obtenga información detallada sobre una campaña específica
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • campaign_id : ID de campaña de meta anuncios
   • Devoluciones: Información detallada sobre la campaña especificada
5. mcp_meta_ads_create_campaign
   • Crear una nueva campaña en una cuenta de Meta Ads
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
     • name : Nombre de la campaña
     • objective : Objetivo de la campaña (CONCIENCIACIÓN, TRÁFICO, COMPROMISO, etc.)
     • status : Estado inicial de la campaña (predeterminado: EN PAUSA)
     • special_ad_categories : Lista de categorías de anuncios especiales, si corresponde
     • daily_budget : Presupuesto diario en la moneda de la cuenta (en centavos)
     • lifetime_budget : Presupuesto de por vida en la moneda de la cuenta (en centavos)
   • Devoluciones: Confirmación con nuevos detalles de la campaña
6. mcp_meta_ads_get_adsets
   • Obtenga conjuntos de anuncios para una cuenta de Meta Ads con filtrado opcional por campaña
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
     • limit : Número máximo de conjuntos de anuncios a devolver (valor predeterminado: 10)
     • campaign_id : ID de campaña opcional para filtrar por
   • Devoluciones: Lista de conjuntos de anuncios que coinciden con los criterios
7. mcp_meta_ads_get_adset_details
   • Obtenga información detallada sobre un conjunto de anuncios específico
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • adset_id : ID del conjunto de anuncios de Meta Ads
   • Devoluciones: información detallada sobre el conjunto de anuncios especificado
8. mcp_meta_ads_get_ads
   • Obtenga anuncios para una cuenta de Meta Ads con filtrado opcional
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
     • limit : Número máximo de anuncios a devolver (predeterminado: 10)
     • campaign_id : ID de campaña opcional para filtrar por
     • adset_id : ID de conjunto de anuncios opcional para filtrar por
   • Devoluciones: Lista de anuncios que coinciden con los criterios
9. mcp_meta_ads_get_ad_details
   • Obtenga información detallada sobre un anuncio específico
   • Entradas:
     • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
     • ad_id : ID de anuncio de meta anuncios
   • Devoluciones: Información detallada sobre el anuncio especificado
10. mcp_meta_ads_get_ad_creatives

• Obtenga detalles creativos para un anuncio específico
• Entradas:
  • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
  • ad_id : ID de anuncio de Meta Ads
• Devoluciones: Detalles creativos que incluyen texto, imágenes y URL

11. mcp_meta_ads_get_ad_image

• Obtenga, descargue y visualice una imagen de anuncio Meta en un solo paso
• Entradas:
  • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
  • ad_id : ID de anuncio de meta anuncios
• Devoluciones: La imagen del anuncio lista para el análisis visual directo

12. mcp_meta_ads_update_ad

• Actualizar un anuncio con nueva configuración
• Entradas:
  • ad_id : ID de anuncio de Meta Ads
  • status : Actualizar el estado del anuncio (ACTIVO, PAUSADO, etc.)
  • bid_amount : Monto de la oferta en la moneda de la cuenta (en centavos de USD)
  • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
• Devoluciones: Confirmación con detalles del anuncio actualizados y un enlace de confirmación.

13. mcp_meta_ads_update_adset

• Actualizar un conjunto de anuncios con nuevas configuraciones, incluidos límites de frecuencia
• Entradas:
  • adset_id : ID del conjunto de anuncios de Meta Ads
  • frequency_control_specs : Lista de especificaciones de control de frecuencia
  • bid_strategy : Estrategia de oferta (p. ej., 'COSTO MÁS BAJO CON LÍMITE DE OFERTA')
  • bid_amount : Monto de la oferta en la moneda de la cuenta (en centavos de USD)
  • status : Actualizar el estado del conjunto de anuncios (ACTIVO, EN PAUSADO, etc.)
  • targeting : Especificaciones de targeting, incluyendo la automatización de targeting
  • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
• Devoluciones: Confirmación con detalles actualizados del conjunto de anuncios y un enlace de confirmación

14. mcp_meta_ads_get_insights

• Obtenga información sobre el rendimiento de una campaña, un conjunto de anuncios, un anuncio o una cuenta
• Entradas:
  • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
  • object_id : ID de la campaña, conjunto de anuncios, anuncio o cuenta
  • time_range : Intervalo de tiempo para la información (predeterminado: máximo)
  • breakdown : dimensión de desglose opcional (por ejemplo, edad, género, país)
  • level : Nivel de agregación (anuncio, conjunto de anuncios, campaña, cuenta)
• Devuelve: métricas de rendimiento para el objeto especificado

15. mcp_meta_ads_debug_image_download

• Depurar problemas de descarga de imágenes e informar diagnósticos detallados
• Entradas:
  • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
  • url : URL de la imagen directa para probar (opcional)
  • ad_id : ID de anuncio de Meta Ads (opcional, se utiliza si no se proporciona la URL)
• Devuelve: Información de diagnóstico sobre los intentos de descarga de imágenes

16. mcp_meta_ads_get_login_link

• Obtenga un enlace de inicio de sesión en el que se pueda hacer clic para la autenticación de Meta Ads
• NOTA: Este método solo debe usarse si usas tu propia aplicación de Facebook. Si usas la autenticación de Pipeboard (recomendado), configura la variable de entorno PIPEBOARD_API_TOKEN (el token se puede obtener en https://pipeboard.co ).
• Entradas:
  • access_token (opcional): token de acceso a la Meta API (se utilizará el token almacenado en caché si no se proporciona)
• Devoluciones: Un enlace de recurso en el que se puede hacer clic para la autenticación Meta

Crear una aplicación Meta Developer

Antes de utilizar el servidor MCP, deberá configurar una aplicación Meta Developer:

1. Vaya a Meta para desarrolladores y cree una nueva aplicación
2. Elija el tipo de aplicación "Consumidor"
3. En la configuración de su aplicación, agregue el producto "API de marketing"
4. Configure la URI de redirección OAuth de su aplicación para incluir http://localhost:8888/callback
5. Anote su ID de aplicación (ID de cliente) para usar con MCP

Autenticación

El MCP de Meta Ads admite dos métodos de autenticación:

1. Autenticación de Pipeboard (Recomendado ⭐)

Este método utiliza Pipeboard.co para administrar la autenticación de Meta API, lo que proporciona tokens de mayor duración y un flujo simplificado:

1. Obtén tu token de Pipeboard : Regístrate en https://pipeboard.co para generar tu token API gratuito
2. Establezca la variable de entorno PIPEBOARD_API_TOKEN con su token:
   export PIPEBOARD_API_TOKEN=your_pipeboard_token
3. Ejecute Meta Ads MCP normalmente: detectará y utilizará automáticamente la autenticación de Pipeboard:
   uvx meta-ads-mcp
4. La primera vez que ejecute un comando, se le proporcionará una URL de inicio de sesión para autorizar con Meta

Beneficios de la autenticación de Pipeboard:

• ✅ Tokens de mayor duración (60 días)
• ✅ No es necesario configurar una aplicación Meta Developer
• ✅ Configuración más sencilla con solo un token API
• ✅ Renovación automática de tokens

Para probar el flujo de autenticación de Pipeboard:

2. Meta OAuth directo (heredado)

El flujo tradicional de OAuth 2.0, diseñado para aplicaciones de escritorio. Este método solo debe usarse si usa su propia aplicación de Facebook en lugar de Pipeboard.

Al autenticarse, hará lo siguiente:

1. Inicie un servidor de devolución de llamadas local en su máquina
2. Abra una ventana del navegador para autenticarse con Meta
3. Solicitarle que autorice la aplicación
4. Redirigir nuevamente al servidor local para extraer y almacenar el token de forma segura

Este método requiere que primero crees una aplicación Meta Developer .

Solución de problemas y registro

El MCP de Meta Ads incluye un sistema de registro integral para ayudar a solucionar problemas:

Ubicación del registro

Los archivos de registro se almacenan en una ubicación específica de la plataforma:

• macOS : ~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log
• Ventanas : %APPDATA%\meta-ads-mcp\meta_ads_debug.log
• Linux : ~/.config/meta-ads-mcp/meta_ads_debug.log

Problemas comunes

Problemas de autenticación

Si tiene problemas de autenticación:

1. Recomendado: utilice la autenticación de Pipeboard
   • Establezca export PIPEBOARD_API_TOKEN=your_token y vuelva a intentarlo
   • Esto proporciona tokens de mayor duración y mejor confiabilidad.
   • Verifica tu token en el panel de Pipeboard
2. Para problemas de ID de aplicación (al usar autenticación directa): si encuentra errores como (#200) Provide valid app ID , verifique lo siguiente:
   • Asegúrese de haber configurado correctamente una aplicación Meta Developer
   • Verifique que esté pasando el ID de aplicación correcto utilizando uno de estos métodos:
     • Establezca la variable de entorno META_APP_ID : export META_APP_ID=your_app_id
     • Páselo como un argumento de línea de comando: meta-ads-mcp --app-id your_app_id

Errores de API

Si recibe errores de la Meta API:

1. Verifique que su aplicación tenga agregado el producto API de marketing
2. Asegúrese de que el usuario tenga los permisos adecuados en las cuentas de anuncios.
3. Comprueba si hay límites de velocidad u otras restricciones en tu aplicación

Comando de depuración

Para problemas específicos de descarga de imágenes, utilice la herramienta de diagnóstico incorporada:

Esto le brindará información detallada sobre el proceso de descarga y posibles problemas.

Ejecutar con diferentes ID de aplicaciones

Si necesita utilizar diferentes ID de meta aplicaciones para distintos propósitos:

Privacidad y seguridad

El MCP de Meta Ads sigue las mejores prácticas de seguridad:

1. Los tokens se almacenan en caché en una ubicación segura específica de la plataforma:
   • Ventanas: %APPDATA%\meta-ads-mcp\token_cache.json o %APPDATA%\meta-ads-mcp\pipeboard_token_cache.json
   • macOS: ~/Library/Application Support/meta-ads-mcp/token_cache.json o ~/Library/Application Support/meta-ads-mcp/pipeboard_token_cache.json
   • Linux: ~/.config/meta-ads-mcp/token_cache.json o ~/.config/meta-ads-mcp/pipeboard_token_cache.json
2. No es necesario que proporciones tu token de acceso para cada comando; se recuperará automáticamente del caché.
3. Puede configurar las siguientes variables de entorno en lugar de pasarlas como argumentos:
   • META_APP_ID : Su ID de meta aplicación (ID de cliente) para el método OAuth directo
   • PIPEBOARD_API_TOKEN : Su token de API de Pipeboard, para el método de autenticación de Pipeboard

Pruebas

Pruebas de CLI

Ejecute el script de prueba para verificar la autenticación y la funcionalidad básica:

Utilice el indicador --force-login para forzar una nueva autenticación incluso si existe un token en caché:

Pruebas de interfaz LLM

Al utilizar Meta Ads MCP con una interfaz LLM (como Claude):

1. Si utiliza la autenticación Meta directa (su propia aplicación de Facebook), pruebe la autenticación llamando a la herramienta mcp_meta_ads_get_login_link
2. Si utiliza la autenticación de Pipeboard (recomendado), asegúrese de que la variable de entorno PIPEBOARD_API_TOKEN esté configurada (el token se puede obtener a través de https://pipeboard.co )
3. Verifique el acceso a la cuenta llamando mcp_meta_ads_get_ad_accounts
4. Verifique los detalles específicos de la cuenta con mcp_meta_ads_get_account_info

Estas funciones manejarán automáticamente la autenticación si es necesario y proporcionarán un enlace de inicio de sesión en el que se puede hacer clic si es necesario.

Solución de problemas

Problemas de autenticación

Si encuentra problemas de autenticación:

1. Al utilizar la interfaz LLM:
   • Si utiliza la autenticación Meta directa (su propia aplicación de Facebook), utilice la herramienta mcp_meta_ads_get_login_link para generar un nuevo enlace de autenticación
   • Si utiliza la autenticación de Pipeboard (recomendado), asegúrese de que la variable de entorno PIPEBOARD_API_TOKEN esté configurada (el token se puede obtener a través de https://pipeboard.co )
   • Asegúrese de hacer clic en el enlace y completar el flujo de autorización en su navegador.
   • Verifique que el servidor de devolución de llamada esté funcionando correctamente (la herramienta lo informará)
2. Al utilizar la autenticación de Pipeboard:
   • Verifique que su PIPEBOARD_API_TOKEN esté configurado correctamente (el token se puede obtener a través de https://pipeboard.co )
   • Compruebe si necesita completar el proceso de autorización visitando la URL de inicio de sesión proporcionada
   • Intente forzar un nuevo inicio de sesión: python test_pipeboard_auth.py --force-login
3. Al utilizar Meta OAuth directo:
   • Ejecute con --force-login para obtener un token nuevo: uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login
   • Asegúrese de que la terminal tenga permisos para abrir una ventana del navegador

Errores de API

Si recibe errores de la Meta API:

1. Verifique que su aplicación tenga agregado el producto API de marketing
2. Asegúrese de que el usuario tenga los permisos adecuados en las cuentas de anuncios.
3. Comprueba si hay límites de velocidad u otras restricciones en tu aplicación

Control de versiones

Puedes comprobar la versión actual del paquete: