Ads Uploader

Documentação

MCP, CLI e API

Configuração do MCP

MCP (Model Context Protocol) é uma forma padrão de apps de IA usarem ferramentas externas. O servidor MCP do Ads Uploader dá ao seu agente de IA a mesma superfície que a CLI usa: navegar por contas, campanhas, conjuntos de anúncios e anúncios, subir mídia, salvar presets, trabalhar com builds salvos, ver a prévia de um build e criar anúncios. Se você conhece o app web ou a CLI, as ferramentas do MCP seguem exatamente o mesmo fluxo.

O acesso ao MCP é para planos pagos e não está disponível durante o teste. Ele usa a mesma conta e a mesma conexão com a Meta do app web e da CLI, e fica desligado sempre que o acesso à CLI é desligado para uma conta.

CLI ou MCP?

Os dois rodam na mesma infraestrutura, então essa é uma escolha de fluxo de trabalho, não de recursos. A CLI é a melhor opção quando você quer conduzir toda a sua operação por um agente de IA: uploads em massa a partir do disco, lançamentos repetidos e builds completos montados pelo terminal.

O MCP é melhor para tarefas pontuais em que o app web continua no processo. Por exemplo:

  • Suba e confira toda a sua mídia no uploader web e depois passe o build ao agente para uma única etapa
  • Peça ao agente para montar a configuração do conjunto de anúncios
  • Peça ao agente para escrever ou reescrever o texto dos seus anúncios
  • Associe textos de anúncio de uma planilha aos nomes dos arquivos dos seus uploads

Os builds salvos conectam os dois. O uploader web, a CLI e o MCP usam as mesmas referências de build, então um build pode ir e voltar sem que ninguém precise digitá-lo de novo. Veja Builds salvos.

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

Use o servidor hospedado quando você trabalha em um app de chat e quer entrar pelo navegador. Adicione esta URL como conector personalizado no seu app:

https://adsuploader.com/api/mcp

No Claude, por exemplo, vá em Settings > Connectors > Add custom connector. ChatGPT e Cursor também aceitam conectores MCP personalizados. Depois de adicionar, conclua o login do Ads Uploader e a tela de consentimento no seu navegador. Não há token para copiar ou colar. Para conferir se funciona, peça ao seu agente para listar suas contas de anúncio.

Conectar com uma chave de API (para seus próprios agentes e scripts)

Entrar com OAuth é a forma normal de conectar um app de IA como Claude ou ChatGPT. Use uma chave de API para conexões de longa duração dos seus próprios agentes e scripts quando não for prático entrar pelo navegador. Crie uma em Account > MCP, CLI & API. Cada chave é para uma pessoa. Veja Chaves de API para saber como criar, usar e revogar.

Envie Authorization: Bearer adk_... para https://adsuploader.com/api/mcp. Para um cliente MCP que aceita cabeçalhos personalizados, a configuração pode ser assim:

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

Conectar um agente de programação (Claude Code, Claude Desktop, Cursor)

Agentes de programação podem usar o mesmo servidor hospedado. No Claude Code, rode:

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

Em outros agentes, adicione https://adsuploader.com/api/mcp como servidor MCP remoto e conclua o login no navegador quando for solicitado. Se o seu agente só aceita servidores locais (stdio), faça a ponte para o servidor hospedado com npx mcp-remote https://adsuploader.com/api/mcp.

Rodar o servidor no seu próprio computador

Você também pode rodar o servidor MCP localmente. Isso é útil quando você quer que o agente suba arquivos direto do seu disco. É preciso ter o Node.js 18 ou mais recente:

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

Depois, adicione o comando ads-mcp às configurações de MCP do seu agente:

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

O servidor local usa o login salvo por ads login. Ele não abre um navegador sozinho, então rode ads login de novo quando esse login expirar (depois de 30 dias).

O que seu agente pode fazer

O servidor dá ao seu agente ferramentas para todo o fluxo de build. Você descreve o que quer em linguagem natural, e o agente chama as ferramentas por você.

ÁreaO que o agente pode fazer
IdentidadeConfirmar com qual usuário do Ads Uploader está conectado antes de mudar qualquer coisa
ContasListar suas contas de anúncio da Meta e passar o accountId certo em cada chamada
NavegaçãoListar campanhas, conjuntos de anúncios, anúncios e Páginas; ler todas as configurações de criativo de um anúncio
SegmentaçãoBuscar chaves de cidade, CEPs e IDs de segmentação detalhada com ads_search_targeting, para nunca precisar adivinhá-los
PresetsListar API presets e presets de texto salvos, ler um preset com ads_get_preset e salvar um anúncio existente como preset
BuildsListar, ler, salvar, atualizar e excluir builds salvos, ou copiar um para um novo rascunho com ads_fork_build para que o original continue como está. Todo build vem com um link que o abre no uploader web.
MídiaSubir imagens e vídeos para a sua conta de anúncio e listar os lotes de upload recentes
PréviaMostrar exatamente o que seria criado antes de qualquer coisa ser feita
CriaçãoCriar anúncios a partir de um preset, de um anúncio copiado, de um build salvo ou de uma especificação completa, e depois acompanhar ou cancelar o job
Duplicar por ID da publicaçãoVer a prévia de uma duplicação por ID da publicação com ads_duplicate_by_post_preview, iniciá-la com ads_duplicate_by_post e acompanhá-la com ads_get_duplication

Veja a prévia primeiro. No servidor hospedado, ads_create acompanha o job por cerca de 60 segundos. Se o job ainda estiver rodando, ele retorna a referência do job, e seu agente continua conferindo com ads_get_job. O job em si roda no servidor e não depende de a conexão continuar aberta. No servidor local, ads_create pode acompanhar por até 30 minutos.

Trabalhar com builds salvos

Os builds são salvos automaticamente enquanto você trabalha no uploader web. Cada um tem uma referência permanente (build_...), mostrada na parte de baixo da etapa de configuração e na janela Saved Builds. Passe essa referência ao seu agente e ele consegue ler exatamente a configuração que você vê, alterá-la e salvá-la de volta no mesmo build.

Se o build estiver aberto no uploader, o uploader pega a alteração salva e a aplica para você quando não há edições não salvas. Você também pode clicar no botão de atualizar ao lado da referência do build para conferir na hora. Se você tiver edições não salvas quando chegar uma alteração externa, o uploader pergunta se você quer carregar as alterações externas ou manter as suas, para que nenhuma versão se perca. Se a aba estiver fechada, peça ao agente o link do build.

Os editores de texto por anúncio e por conjunto de anúncios no uploader web têm botões do Claude e do ChatGPT que abrem um chat com a referência do seu build já preenchida, então passar uma revisão de texto leva um clique. Também funciona no sentido contrário: peça ao agente para salvar o trabalho dele como build e depois abra o link para conferir tudo no navegador antes de qualquer anúncio ser criado.

Subir mídia

A forma como os arquivos chegam à sua conta de anúncio depende de onde o servidor roda:

  • Servidor hospedado (apps de chat e agentes de programação que usam a URL hospedada): passe ao agente links públicos de download HTTPS, um link público de arquivo do Google Drive ou um único link público de pasta do Drive. O Ads Uploader baixa e processa os arquivos em segundo plano, então os dados dos arquivos nunca passam pelo chat.
  • Servidor local (ads-mcp): o agente também pode subir arquivos direto do seu disco. Você também pode usar a CLI com ads upload para pastas no seu computador.

Depois que um upload por link ou pelo Drive começa, o agente confere o andamento com ads_get_upload. Quando ele termina, o resultado inclui o resumo do lote usado nas prévias e na criação de anúncios. Para interromper uma importação indesejada, o agente chama ads_cancel_job; os arquivos que já terminaram continuam utilizáveis, e o resultado mostra quantos foram concluídos, falharam ou foram ignorados. Imagens com nome *_thumbnail são anexadas ao vídeo correspondente como thumbnails personalizadas em vez de contarem como mídia separada, então o total de mídia de uma pasta pode ser menor que o número de arquivos. Se o Google bloquear a importação de uma pasta por um tempo, o resultado diz o que foi concluído, o que falhou e o que foi ignorado, para que o agente possa avisar você para tentar de novo mais tarde.

Os links do Drive precisam estar compartilhados como Anyone with the link (Viewer). Arquivos privados do Drive são um recurso do uploader web.

Imagens pequenas também podem ser enviadas inline (até 10 MB no total por chamada). Um agente de programação que consegue enviar os dados dos arquivos por conta própria pode pedir o caminho antigo de upload direto, que sobe para o armazenamento do Ads Uploader. Só esse caminho precisa de acesso de saída ao nosso host de upload. Se o seu agente roda em um sandbox de rede, libere *.adsuploader.com na allowlist de rede ou de sandbox do seu agente. A resposta do upload informa o host exato em allowlistHost; se algum dia ele for diferente, confie na resposta.

Limites

  • 50 arquivos por chamada de upload. Divida uploads maiores em várias chamadas.
  • Limites de requisição. As chamadas são limitadas por usuário e por tipo de chamada em uma janela móvel de um minuto (por exemplo, 120 chamadas de ferramentas MCP por minuto, e 20 por minuto para cada tipo de chamada de listagem ou de prévia). O uso normal fica bem abaixo desses limites. Se o seu agente atingir um limite, ele recebe um erro de "rate limit" e deve esperar antes de tentar de novo.
  • Um job de criação de anúncios por vez por usuário, igual à CLI.

Login e acesso

O servidor hospedado faz o seu login com OAuth, o fluxo padrão de "entrar e aprovar". O token de acesso que ele emite dura uma hora. Se o seu app aceitar refresh tokens, ele também recebe um refresh token que dura 30 dias e o usa para renovar o token de acesso em segundo plano, então você não precisa entrar a cada sessão. Caso contrário, o app pede que você entre de novo quando o token expirar.

O acesso acompanha a sua conta: é só para planos pagos, e desligar o acesso à CLI de uma conta também remove o acesso dela ao MCP na hora.

Anúncios de parceria

As ferramentas ads_preview e ads_create do MCP aceitam as mesmas especificações de parceria da CLI:

  • Com a sua própria mídia: adicione profile.partnership.enabled: true com os IDs do seu parceiro a uma especificação normal de mídia. Você pode definir um parceiro diferente por anúncio ou por conjunto de anúncios.
  • A partir de publicações existentes do Instagram: importe uma publicação autorizada com mediaItems[].kind: "partnershipPost".

A prévia mostra o parceiro, a aprovação e o modo de cabeçalho de cada anúncio, agrupados por conjunto de anúncios. Para os formatos completos da especificação e os limites, veja Anúncios de parceria com a sua própria mídia e Especificação de parceria com publicação existente do Instagram.

Product Showcase

Product Showcase mostra produtos de um catálogo sob um anúncio com uma única imagem ou um único vídeo. Os anúncios de catálogo completo (dinâmicos/DPA) ainda não são suportados.

Os IDs devem ser cadeias de dígitos. As recomendações exigem campanhas de Vendas (OUTCOME_SALES); a seleção manual de catálogo e conjunto também funciona com outros objetivos. Product Showcase não pode ser ativado em carrosséis, formatos flexíveis, multimédia, publicações existentes ou anúncios Partnership.

Consulte catálogos e conjuntos e peça uma recomendação:

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

Create e Preview aceitam productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? }; enabled é true por predefinição. Omitir o campo mantém o criativo de origem. RECOMMENDED usa a escolha Meta (choiceSource: "DEFAULT"); MUST_PICK exige um ID candidato como productSetId ("MANUAL"). MANUAL exige catálogo e conjunto. Uma escolha diferente validada usa "MANUAL".

Opções Create e Preview: --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Apenas IDs significa on; recommended define useRecommendation: true. Off define { enabled: false }, não aceita IDs e mantém o conjunto do anúncio de origem.

Preview devolve productShowcase com enabled, IDs, nome opcional, choiceSource e source (recommendation, manual, source_ad), ou null. As recomendações são só de leitura. Test Mode exige IDs quando ativado, não consulta catálogos e indica que não foram verificados. As escolhas guardadas na interface são convertidas; as predefinições são verificadas novamente no lançamento.

←
Previous
Referência completa da CLI
Next
Ads Insights (Beta)
→