Ads Uploader

Documentación

MCP, CLI y API

Configuración del MCP

MCP (Model Context Protocol) es una forma estándar de que las apps de IA usen herramientas externas. El servidor MCP de Ads Uploader le da a tu agente de IA lo mismo que usa el CLI: explorar cuentas, campañas, conjuntos de anuncios y anuncios, subir medios, guardar preajustes, trabajar con builds guardados, previsualizar un build y crear anuncios. Si conoces la app web o el CLI, las herramientas del MCP siguen exactamente el mismo flujo de trabajo.

El acceso al MCP es para planes de pago y no está disponible durante la prueba. Usa la misma cuenta y la misma conexión con Meta que la app web y el CLI, y se desactiva siempre que se desactiva el acceso al CLI de una cuenta.

¿CLI o MCP?

Los dos funcionan sobre la misma infraestructura, así que es una elección de flujo de trabajo, no de funciones. El CLI encaja mejor cuando quieres llevar toda tu operación a través de un agente de IA: subidas masivas desde el disco, lanzamientos repetidos y builds completos armados desde la terminal.

El MCP es mejor para tareas concretas en las que la app web sigue en el circuito. Por ejemplo:

  • Sube y revisa todos tus medios en el uploader web y luego pásale el build al agente para un solo paso
  • Haz que el agente prepare la configuración de los conjuntos de anuncios
  • Haz que el agente escriba o reescriba los textos de tus anuncios
  • Empareja los textos de los anuncios de una hoja de cálculo con los nombres de archivo de tus subidas

Los builds guardados conectan las dos cosas. El uploader web, el CLI y el MCP usan las mismas referencias de build, así que un build puede ir y venir sin que nadie tenga que volver a escribirlo. Consulta Builds guardados.

Conectar una app de chat (Claude, ChatGPT, Cursor)

Usa el servidor alojado cuando trabajes desde una app de chat y quieras iniciar sesión desde tu navegador. Añade esta URL como conector personalizado en tu app:

https://adsuploader.com/api/mcp

Por ejemplo, en Claude ve a Settings > Connectors > Add custom connector. ChatGPT y Cursor también admiten conectores MCP personalizados. Después de añadirlo, completa en tu navegador el inicio de sesión de Ads Uploader y la pantalla de consentimiento. No hay ningún token que copiar ni pegar. Para comprobar que funciona, pídele a tu agente que liste tus cuentas publicitarias.

Conectar con una clave API (para tus propios agentes y scripts)

Iniciar sesión con OAuth es la forma normal de conectar una app de IA como Claude o ChatGPT. Usa una clave API para conexiones de larga duración de tus propios agentes y scripts cuando no resulte práctico iniciar sesión desde un navegador. Crea una en Account > MCP, CLI & API. Cada clave es para una persona. Consulta Claves API para aprender a crearla, usarla y revocarla.

Envía Authorization: Bearer adk_... a https://adsuploader.com/api/mcp. En un cliente MCP que admita encabezados personalizados, la configuración puede ser así:

{
  "mcpServers": {
    "ads-uploader": {
      "url": "https://adsuploader.com/api/mcp",
      "headers": { "Authorization": "Bearer adk_..." }
    }
  }
}

Conectar un agente de programación (Claude Code, Claude Desktop, Cursor)

Los agentes de programación pueden usar el mismo servidor alojado. En Claude Code, ejecuta:

claude mcp add --transport http ads-uploader https://adsuploader.com/api/mcp

En otros agentes, añade https://adsuploader.com/api/mcp como servidor MCP remoto y completa el inicio de sesión en el navegador cuando te lo pida. Si tu agente solo admite servidores locales (stdio), conéctalo al servidor alojado con npx mcp-remote https://adsuploader.com/api/mcp.

Ejecutar el servidor en tu propia computadora

También puedes ejecutar el servidor MCP en local. Es útil cuando quieres que el agente suba archivos directamente desde tu disco. Necesita Node.js 18 o posterior:

npm install -g @adsuploader/cli @adsuploader/mcp
ads login

Luego añade el comando ads-mcp a la configuración MCP de tu agente:

{
  "mcpServers": {
    "ads-uploader": {
      "command": "ads-mcp"
    }
  }
}

El servidor local usa el inicio de sesión guardado por ads login. No abre un navegador por sí mismo, así que vuelve a ejecutar ads login cuando ese inicio de sesión caduque (a los 30 días).

Qué puede hacer tu agente

El servidor le da a tu agente herramientas para todo el flujo de trabajo de un build. Describes lo que quieres en lenguaje natural y el agente llama a las herramientas por ti.

ÁreaQué puede hacer el agente
IdentidadConfirmar con qué usuario de Ads Uploader ha iniciado sesión antes de cambiar nada
CuentasListar tus cuentas publicitarias de Meta y pasar el accountId correcto en cada llamada
ExploraciónListar campañas, conjuntos de anuncios, anuncios y páginas; leer toda la configuración de la creatividad de un anuncio
SegmentaciónBuscar claves de ciudad, códigos postales e IDs de segmentación detallada con ads_search_targeting, para no tener que adivinarlos nunca
PreajustesListar los preajustes de API y de texto guardados, leer un preajuste con ads_get_preset y guardar un anuncio existente como preajuste
BuildsListar, leer, guardar, actualizar y eliminar builds guardados, o copiar uno en un borrador nuevo con ads_fork_build para que el original se quede como está. Cada build incluye un enlace que lo abre en el uploader web.
MediosSubir imágenes y videos a tu cuenta publicitaria y listar los lotes de subida recientes
Vista previaMostrar exactamente lo que se crearía antes de crear nada
CrearCrear anuncios a partir de un preajuste, un anuncio copiado, un build guardado o una especificación completa, y luego seguir o cancelar el trabajo
Duplicar por Post IDPrevisualizar una duplicación por Post ID con ads_duplicate_by_post_preview, iniciarla con ads_duplicate_by_post y seguirla con ads_get_duplication

Previsualiza primero. En el servidor alojado, ads_create sigue el trabajo durante unos 60 segundos. Si el trabajo sigue en curso, devuelve la referencia del trabajo y tu agente lo sigue consultando con ads_get_job. El trabajo se ejecuta en el servidor y no depende de que la conexión siga abierta. En el servidor local, ads_create puede seguirlo durante un máximo de 30 minutos.

Trabajar con builds guardados

Los builds se guardan automáticamente mientras trabajas en el uploader web. Cada uno tiene una referencia permanente (build_...), que aparece al final del paso de configuración y en la ventana Saved Builds. Dale esa referencia a tu agente y podrá leer exactamente la configuración que ves, cambiarla y guardarla en el mismo build.

Si el build está abierto en el uploader, el uploader recoge el cambio guardado y lo aplica por ti cuando no tienes ediciones sin guardar. También puedes hacer clic en el botón de actualizar junto a la referencia del build para comprobarlo al momento. Si tienes ediciones sin guardar cuando llega un cambio externo, el uploader te pregunta si quieres cargar los cambios externos o conservar los tuyos, así que no se pierde ninguna de las dos versiones. Si la pestaña está cerrada, pídele al agente el enlace del build.

Los editores de texto por anuncio y por conjunto de anuncios del uploader web tienen botones de Claude y ChatGPT que abren un chat con la referencia de tu build ya escrita, así que pasarle una revisión de textos lleva un solo clic. También funciona al revés: pídele al agente que guarde su trabajo como un build y luego abre el enlace para revisarlo todo en el navegador antes de que se cree ningún anuncio.

Subir medios

Cómo llegan los archivos a tu cuenta publicitaria depende de dónde se ejecuta el servidor:

  • Servidor alojado (apps de chat y agentes de programación que usan la URL alojada): dale al agente enlaces de descarga HTTPS públicos, un enlace público a un archivo de Google Drive o un enlace público a una carpeta de Drive. Ads Uploader descarga y procesa los archivos en segundo plano, así que los datos de los archivos nunca pasan por el chat.
  • Servidor local (ads-mcp): el agente también puede subir archivos directamente desde tu disco. También puedes usar el CLI con ads upload para carpetas de tu computadora.

Cuando empieza una subida por enlace o desde Drive, el agente la consulta con ads_get_upload. Cuando termina, el resultado incluye el resumen del lote que se usa para las vistas previas y la creación de anuncios. Para detener una importación que no quieres, el agente llama a ads_cancel_job; los archivos que ya terminaron siguen siendo utilizables, y el resultado muestra cuántos se completaron, fallaron o se omitieron. Las imágenes con nombre *_thumbnail se adjuntan a su video correspondiente como miniaturas personalizadas en lugar de contarse como medios separados, así que el total de medios de una carpeta puede ser menor que su número de archivos. Si Google bloquea durante un tiempo la importación de una carpeta, el resultado indica qué se completó, qué falló y qué se omitió, para que el agente pueda decirte que lo intentes más tarde.

Los enlaces de Drive deben estar compartidos como Anyone with the link (Viewer). Los archivos privados de Drive son una función del uploader web.

Las imágenes pequeñas también se pueden enviar en línea (hasta 10 MB en total por llamada). Un agente de programación que pueda enviar datos de archivos por sí mismo puede pedir la ruta de subida directa anterior, que sube al almacenamiento de Ads Uploader. Solo esa ruta necesita acceso saliente a nuestro host de subida. Si tu agente se ejecuta en un sandbox de red, permite *.adsuploader.com en la lista de permitidos de red o del sandbox de tu agente. La respuesta de la subida indica el host exacto en allowlistHost; si alguna vez es distinto, fíate de la respuesta.

Límites

  • 50 archivos por llamada de subida. Divide las subidas más grandes en varias llamadas.
  • Límites de solicitudes. Las llamadas están limitadas por usuario y por tipo de llamada en un minuto móvil (por ejemplo, 120 llamadas a herramientas del MCP por minuto y 20 por minuto para cada tipo de llamada de listado o de vista previa). El uso normal se queda muy por debajo. Si tu agente llega a un límite, recibe un error "rate limit" y debe esperar antes de volver a intentarlo.
  • Un trabajo de creación de anuncios a la vez por usuario, igual que en el CLI.

Inicio de sesión y acceso

El servidor alojado te hace iniciar sesión con OAuth, el flujo estándar de "inicia sesión y aprueba". El token de acceso que emite dura una hora. Si tu app admite tokens de actualización, también recibe un token de actualización que dura 30 días y lo usa para renovar el token de acceso en segundo plano, así que no tienes que iniciar sesión en cada sesión. Si no, la app te pide que vuelvas a iniciar sesión cuando el token caduca.

El acceso depende de tu cuenta: es solo para planes de pago, y desactivar el acceso al CLI de una cuenta también le quita al momento el acceso al MCP.

Anuncios de partnership

Las herramientas ads_preview y ads_create del MCP aceptan las mismas especificaciones de partnership que el CLI:

  • Con tus propios medios: añade profile.partnership.enabled: true con los IDs de tu socio a una especificación normal de medios. Puedes definir un socio distinto por anuncio o por conjunto de anuncios.
  • Desde publicaciones existentes de Instagram: importa una publicación autorizada con mediaItems[].kind: "partnershipPost".

La vista previa muestra el socio, la aprobación y el modo de cabecera de cada anuncio, agrupados por conjunto de anuncios. Para ver las formas completas de la especificación y los límites, consulta Anuncios de partnership con tus propios medios y Especificación de partnership con publicación existente de Instagram.

Product Showcase

Product Showcase muestra productos de un catálogo debajo de un anuncio de una sola imagen o vídeo. Los anuncios de catálogo completo (dinámicos/DPA) aún no son compatibles.

Los IDs deben ser cadenas de dígitos. Las recomendaciones requieren campañas de Ventas (OUTCOME_SALES); la selección manual de catálogo y conjunto también funciona con otros objetivos. No se admite Product Showcase en anuncios de carrusel, flexibles, multimedia, publicaciones existentes ni Partnership.

Consulta catálogos y conjuntos y solicita una recomendación:

  • ads_list_catalogs({ accountId })
  • ads_list_product_sets({ accountId, catalogId, productSetId? })
  • ads_get_product_showcase_recommendation({ accountId, adUrl, pageId?, pixelId? })

Create y Preview aceptan productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? }; enabled vale true por defecto. Si se omite, se hereda el anuncio de origen. RECOMMENDED usa el valor de Meta (choiceSource: "DEFAULT"); MUST_PICK exige un ID candidato como productSetId ("MANUAL"). MANUAL requiere catálogo y conjunto. Los IDs alternativos validados usan "MANUAL".

Flags de Create y Preview: --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Solo IDs equivale a on; recommended establece useRecommendation: true. Off establece { enabled: false }, no admite IDs y conserva el conjunto del anuncio de origen.

Preview devuelve productShowcase con enabled, IDs, nombre opcional, choiceSource y source (recommendation, manual, source_ad), o null. Las recomendaciones son de solo lectura. Test Mode exige IDs cuando está activado, no consulta catálogos e indica que no se verificaron. Las selecciones guardadas de la interfaz se convierten; los valores predeterminados se revisan al lanzar.

←
Previous
Referencia completa del CLI
Next
Ads Insights (Beta)
→