googleads-automation

Automação de Google Ads via Rube MCP

Acesse dados do Google Ads por meio da integração com Google Analytics, execute relatórios de desempenho, liste contas de Ads vinculadas e analise métricas de campanhas usando Rube MCP (Composio).

Documentação do toolkit: composio.dev/toolkits/googleads

Pré-requisitos

• Rube MCP deve estar conectado (RUBE_SEARCH_TOOLS disponível)
• Conexão ativa via RUBE_MANAGE_CONNECTIONS com o toolkit google_analytics
• Sempre chame RUBE_SEARCH_TOOLS primeiro para obter os esquemas atuais das ferramentas

Configuração

Obter Rube MCP: Adicione https://rube.app/mcp como um servidor MCP na configuração do seu cliente. Não são necessárias chaves de API — basta adicionar o endpoint e funciona.

1. Verifique se o Rube MCP está disponível confirmando que RUBE_SEARCH_TOOLS responde
2. Chame RUBE_MANAGE_CONNECTIONS com o toolkit google_analytics
3. Se a conexão não estiver ATIVA, siga o link de autenticação retornado para concluir a configuração
4. Confirme que o status da conexão mostra ATIVO antes de executar qualquer fluxo de trabalho

Nota: Os dados do Google Ads são acessados por meio da integração do toolkit do Google Analytics. As ferramentas abaixo usam propriedades GA4 vinculadas a contas do Google Ads.

Fluxos de Trabalho Principais

1. Listar Links do Google Ads para uma Propriedade

Use GOOGLE_ANALYTICS_ANALYTICS_ADMIN_PROPERTIES_GOOGLE_ADS para recuperar todos os links de contas do Google Ads configurados para uma propriedade GA4.

Ferramente: GOOGLE_ANALYTICS_ANALYTICS_ADMIN_PROPERTIES_GOOGLE_ADS
Parâmetros:
  - parent (obrigatório): Nome do recurso da propriedade (formato: "properties/{propertyId}")
  - pageSize: Máximo de resultados (1-200, padrão 50)
  - pageToken: Token de paginação

2. Executar um Relatório de Desempenho GA4

Use GOOGLE_ANALYTICS_RUN_REPORT para executar relatórios personalizados com dimensões, métricas, intervalos de datas e filtros.

Ferramente: GOOGLE_ANALYTICS_RUN_REPORT
Parâmetros:
  - property (obrigatório): Recurso da propriedade (formato: "properties/{property_id}")
  - dimensions: Array de objetos de dimensão (ex.: [{"name": "sessionCampaignName"}, {"name": "date"}])
  - metrics: Array de objetos de métrica (ex.: [{"name": "sessions"}, {"name": "totalRevenue"}])
  - dateRanges: Array com startDate e endDate (ex.: [{"startDate": "2025-01-01", "endDate": "2025-01-31"}])
  - dimensionFilter: Filtro por valores de dimensão
  - metricFilter: Filtro por valores de métrica (aplicado após agregação)
  - orderBys: Ordenar resultados
  - limit: Máximo de linhas a retornar (1-250000)

3. Verificar Compatibilidade de Dimensão/Métrica

Use GOOGLE_ANALYTICS_CHECK_COMPATIBILITY para validar combinações de dimensões e métricas antes de executar um relatório.

Ferramente: GOOGLE_ANALYTICS_CHECK_COMPATIBILITY
Descrição: Valida a compatibilidade das dimensões ou métricas escolhidas
  antes de executar um relatório.
Nota: Chame RUBE_SEARCH_TOOLS para obter o esquema completo desta ferramenta.

4. Listar Contas GA4

Use GOOGLE_ANALYTICS_LIST_ACCOUNTS para enumerar todas as contas do Google Analytics acessíveis.

Ferramente: GOOGLE_ANALYTICS_LIST_ACCOUNTS
Parâmetros:
  - pageSize: Máximo de contas a retornar
  - pageToken: Token de paginação
  - showDeleted: Incluir contas excluídas suavemente

5. Listar Propriedades GA4 em uma Conta

Use GOOGLE_ANALYTICS_LIST_PROPERTIES para listar propriedades de uma conta GA4 específica.

Ferramente: GOOGLE_ANALYTICS_LIST_PROPERTIES
Parâmetros:
  - account (obrigatório): Nome do recurso da conta (formato: "accounts/{account_id}")
  - pageSize: Máximo de propriedades (1-200)
  - pageToken: Token de paginação
  - showDeleted: Incluir propriedades na lixeira

6. Obter Dimensões e Métricas Disponíveis

Use GOOGLE_ANALYTICS_GET_METADATA para descobrir todos os campos disponíveis para criar relatórios.

Ferramente: GOOGLE_ANALYTICS_GET_METADATA
Descrição: Obtém metadados de dimensões, métricas e comparações
  para uma propriedade GA4.
Nota: Chame RUBE_SEARCH_TOOLS para obter o esquema completo desta ferramenta.

Padrões Comuns

• Descubra e depois relate: Use GOOGLE_ANALYTICS_LIST_ACCOUNTS para encontrar IDs de conta, depois GOOGLE_ANALYTICS_LIST_PROPERTIES para encontrar IDs de propriedade e, em seguida, GOOGLE_ANALYTICS_RUN_REPORT para extrair dados.
• Valide antes de consultar: Use GOOGLE_ANALYTICS_CHECK_COMPATIBILITY para validar combinações de dimensão/métrica antes de executar relatórios e evitar erros 400.
• Desempenho de campanha: Execute relatórios com dimensões como sessionCampaignName, sessionSource, sessionMedium e métricas como sessions, activeUsers, totalRevenue.
• Descoberta de links de Ads: Use GOOGLE_ANALYTICS_ANALYTICS_ADMIN_PROPERTIES_GOOGLE_ADS para descobrir quais contas do Google Ads estão vinculadas a cada propriedade GA4.
• Descoberta de campos: Use GOOGLE_ANALYTICS_GET_METADATA para listar todas as dimensões e métricas disponíveis antes de construir relatórios complexos.

Armadilhas Conhecidas

• Compatibilidade dimensão/métrica: A API do GA4 possui regras estritas de compatibilidade. Nem todas as dimensões podem ser combinadas com todas as métricas. Dimensões demográficas (ex.: userAgeBracket, userGender) são frequentemente incompatíveis com dimensões/filtros no escopo da sessão (ex.: sessionCampaignName, sessionSource).
• dateRange NÃO é uma dimensão: Não inclua dateRange no array de dimensões. Use date, dateHour, year, month ou week em vez disso.
• exits NÃO é válido: Nem exits como dimensão nem como métrica é válido no GA4.
• Formato do ID da propriedade: Deve ser properties/{numeric_id} (ex.: properties/123456789). Não use IDs de conta do Google (IDs OAuth longos).
• Formato do ID da conta: Deve ser accounts/{numeric_id} onde o ID numérico tem 6-10 dígitos.
• Separação de filtros: Use dimensionFilter apenas para campos de dimensão e metricFilter apenas para campos de métrica. Misturá-los causará erros.
• Máximo de 9 dimensões e 10 métricas por solicitação de relatório.

Referência Rápida

Ação	Ferramenta	Parâmetros Chave
Listar links de Ads	GOOGLE_ANALYTICS_ANALYTICS_ADMIN_PROPERTIES_GOOGLE_ADS	parent
Executar relatório	GOOGLE_ANALYTICS_RUN_REPORT	property, dimensions, metrics, dateRanges
Verificar compatibilidade	GOOGLE_ANALYTICS_CHECK_COMPATIBILITY	(veja esquema completo via RUBE_SEARCH_TOOLS)
Listar contas	GOOGLE_ANALYTICS_LIST_ACCOUNTS	pageSize
Listar propriedades	GOOGLE_ANALYTICS_LIST_PROPERTIES	account, pageSize
Obter metadados	GOOGLE_ANALYTICS_GET_METADATA	(veja esquema completo via RUBE_SEARCH_TOOLS)

---

Desenvolvido por Composio