Meta Ads MCP

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 : Cómo usar un LLM para comprender el rendimiento de sus anuncios:

Inicio rápido

1. Regístrese en Pipeboard para autenticarse con Meta (alternativamente, puede configurar su propia aplicación meta personalizada )
2. Obtén tu token de Pipeboard en pipeboard.co/api-tokens
3. Agregue esta configuración a su cliente MCP:

¡Listo! Ya puedes usar Meta Ads MCP en tu cliente MCP favorito.

Nota : Si prefiere utilizar su propia aplicación Meta Developer en lugar de la autenticación de Pipeboard, consulte CUSTOM_META_APP.md para obtener instrucciones.

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

Configuración avanzada

Instalación de desarrollo

Si estás contribuyendo al proyecto o necesitas ejecutarlo directamente:

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
   • macOS: ~/Library/Application Support/meta-ads-mcp/token_cache.json
   • Linux: ~/.config/meta-ads-mcp/token_cache.json
2. No es necesario que proporciones tu token de acceso para cada comando; se recuperará automáticamente del caché.

Pruebas

Pruebas de interfaz LLM

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

1. Asegúrese de que la variable de entorno PIPEBOARD_API_TOKEN esté configurada
2. Verifique el acceso a la cuenta llamando mcp_meta_ads_get_ad_accounts
3. Verifique los detalles específicos de la cuenta con mcp_meta_ads_get_account_info

Solución de problemas

Problemas de autenticación

Si encuentra problemas de autenticación:

1. Verifique la configuración de su Pipeboard:
   • Compruebe que PIPEBOARD_API_TOKEN esté configurado correctamente
   • Verifica tu token en el panel de Pipeboard
   • Intente forzar un nuevo inicio de sesión: python test_pipeboard_auth.py --force-login
2. Al utilizar la interfaz LLM:
   • Asegúrese de que la variable de entorno PIPEBOARD_API_TOKEN esté configurada
   • Compruebe que el servidor de devolución de llamadas se esté ejecutando correctamente

Errores de API

Si recibe errores de la Meta API:

1. Asegúrese de que el usuario tenga los permisos adecuados en las cuentas de anuncios.
2. Comprueba si hay límites de velocidad u otras restricciones
3. Verifique que su token de Pipeboard no haya expirado

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

Configuración

Autenticación de Pipeboard

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

1. Regístrate en Pipeboard.co y genera un token API
2. Establezca la variable de entorno:
   export PIPEBOARD_API_TOKEN=your_pipeboard_token
3. Ejecute meta-ads-mcp: se encargará de la autenticación automáticamente

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:

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_account_pages
   • Obtener páginas asociadas con 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) o "me" para las páginas del usuario actual
   • Devoluciones: Lista de páginas asociadas a la cuenta, útiles para la creación y gestión de anuncios.
4. 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
5. 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
6. 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
7. 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
8. 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
9. mcp_meta_ads_create_adset
   • Crear un nuevo conjunto de anuncios en una cuenta de Meta Ads
   • Entradas:
     • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
     • campaign_id : ID de campaña de meta anuncios a la que pertenece este conjunto de anuncios
     • name : Nombre del conjunto de anuncios
     • status : Estado inicial del conjunto de anuncios (predeterminado: EN PAUSA)
     • daily_budget : Presupuesto diario en la moneda de la cuenta (en centavos) como una cadena
     • lifetime_budget : Presupuesto de por vida en la moneda de la cuenta (en centavos) como una cadena
     • targeting : especificaciones de segmentación (por ejemplo, edad, ubicación, intereses)
     • optimization_goal : Objetivo de optimización de conversión (por ejemplo, 'LINK_CLICKS')
     • billing_event : cómo se le cobra (por ejemplo, 'IMPRESIONES')
     • bid_amount : Monto de la oferta en la moneda de la cuenta (en centavos)
     • bid_strategy : Estrategia de oferta (por ejemplo, 'LOWEST_COST')
     • start_time , end_time : Horas de inicio y finalización opcionales (ISO 8601)
     • access_token (opcional): token de acceso a la Meta API
   • Devoluciones: Confirmación con nuevos detalles del conjunto de anuncios
10. 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

11. mcp_meta_ads_create_ad

• Crear un nuevo anuncio con una creatividad existente
• Entradas:
  • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
  • name : Nombre del anuncio
  • adset_id : ID del conjunto de anuncios donde se colocará este anuncio
  • creative_id : ID de una creatividad existente para usar
  • status : Estado inicial del anuncio (predeterminado: EN PAUSA)
  • bid_amount : Monto de oferta opcional (en centavos)
  • tracking_specs : Especificaciones de seguimiento opcionales
  • access_token (opcional): token de acceso a la Meta API
• Devoluciones: Confirmación con nuevos detalles del anuncio

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

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

14. mcp_meta_ads_create_ad_creative

• Cree un nuevo anuncio creativo usando un hash de imagen cargado
• Entradas:
  • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
  • name : Nombre creativo
  • image_hash : Hash de la imagen cargada
  • page_id : ID de la página de Facebook para el anuncio
  • link_url : URL de destino
  • message : Copia/texto del anuncio
  • headline : titular del anuncio
  • description : Descripción del anuncio
  • call_to_action_type : tipo de botón CTA (p. ej., 'APRENDER_MÁS')
  • instagram_actor_id : ID de cuenta de Instagram opcional
  • access_token (opcional): token de acceso a la Meta API
• Devoluciones: Confirmación con nuevos detalles creativos

15. mcp_meta_ads_upload_ad_image

• Sube una imagen para usarla en creatividades de Meta Ads
• Entradas:
  • account_id : ID de la cuenta de Meta Ads (formato: act_XXXXXXXXX)
  • image_path : Ruta al archivo de imagen para cargar
  • name : Nombre opcional para la imagen
  • access_token (opcional): token de acceso a la Meta API
• Devoluciones: Respuesta JSON con detalles de la imagen, incluido el hash

16. 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 Ads
• Devoluciones: La imagen del anuncio lista para el análisis visual directo

17. mcp_meta_ads_update_ad

• Actualizar un anuncio con nueva configuración
• Entradas:
  • ad_id : ID de anuncio de meta anuncios
  • 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.

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

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

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

21. 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
• 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

22. mcp_meta-ads_create_budget_schedule

• Crea un cronograma de presupuesto para una campaña de Meta Ads.
• Entradas:
  • campaign_id : ID de la campaña de meta anuncios.
  • budget_value : Monto del aumento del presupuesto.
  • budget_value_type : Tipo de valor de presupuesto ("ABSOLUTO" o "MULTIPLIFICADOR").
  • time_start : marca de tiempo de Unix que indica cuándo debe comenzar el período de alta demanda.
  • time_end : marca de tiempo de Unix que indica cuándo debe finalizar el período de alta demanda.
  • access_token (opcional): token de acceso a la Meta API.
• Devuelve: cadena JSON con el ID del programa de presupuesto creado o un mensaje de error.