Servidor MCP do Google Ads: guia de integração para desenvolvedores

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que permite que modelos de linguagem grandes (LLMs) interajam com segurança com dados e aplicativos externos. O servidor MCP do Google Ads fornece uma ponte padronizada para a API Google Ads, que permite que os agentes de IA analisem e recuperem dados de campanhas usando linguagem natural.

Recursos e suporte da comunidade

• Repositório do GitHub:encontre demonstrações, exemplos e relate bugs ou sugira recursos no repositório google-ads-mcp.

  Use a guia "Issues" para relatórios de bugs e solicitações de recursos.

• Comunidade:participe do canal #ads-api-ai-tools no Discord da Comunidade de Publicidade do Google.

Visão geral técnica

Ao implementar esse servidor MCP, você não precisa escrever um "código de cola" personalizado para autenticação da API Google Ads, busca de recursos e análise de dados. O servidor expõe ferramentas específicas que um LLM pode descobrir e invocar de forma autônoma.

Principais especificações

• Protocolo:MCP (Protocolo de Contexto de Modelo)
• Modo:somente leitura (versão atual)
• Linguagem:Python
• Transporte:entrada padrão (stdio) ou HTTP transmissível (streamable-http / Cloud Run)
• Autenticação:OAuth 2.0 ou conta de serviço

Como funciona o ciclo de interação

1. Solicitação:um usuário envia uma consulta como "Como está a performance da minha campanha esta semana?".
2. Descoberta:o LLM inspeciona as ferramentas disponíveis e identifica os recursos de pesquisa do google-ads-mcp.
3. Execução:o servidor MCP executa a lógica Python para consultar a API Google Ads.
4. Injeção de contexto:os resultados estruturados são retornados para a janela de contexto do LLM.
5. Resposta:o LLM sintetiza os dados em uma resposta legível por humanos.

Primeiros passos

Siga estas etapas para configurar e usar o servidor MCP do Google Ads.

Pré-requisitos

Antes da configuração, verifique se você tem as seguintes credenciais do console do Google Cloud:

• ID do projeto:o ID do seu projeto do Google Cloud (GOOGLE_PROJECT_ID). Verifique a página de visão geral da API Google Ads para garantir que seu projeto tenha níveis de acesso Explorer, básico ou padrão. Caso contrário, solicite um desses níveis de acesso. Os tokens de desenvolvedor (GOOGLE_ADS_DEVELOPER_TOKEN) foram descontinuados em 9 de setembro de 2026 e não são mais necessários na versão mais recente do servidor MCP do Google Ads, porque os níveis de acesso à API estão associados ao projeto na nuvem do Google Cloud.
• Credenciais do OAuth:um par de ID do cliente/chave secreta do cliente do OAuth 2.0 ou um conjunto de credenciais padrão do aplicativo.

Configuração

Para integrar o servidor a um host compatível com MCP, adicione a seguinte entrada ao arquivo de configuração MCP do host, como settings.json, e aponte GOOGLE_APPLICATION_CREDENTIALS para o arquivo JSON do ADC (ou configure o ADC padrão com gcloud auth application-default login). Se você acessar contas por uma conta de administrador, também poderá definir GOOGLE_ADS_LOGIN_CUSTOMER_ID. Consulte a documentação do host para saber o local exato e o nome do arquivo dessa configuração.

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Opcional: equipe seu agente com habilidades e o Assistente para Desenvolvedores

O servidor MCP do Google Ads dá ao seu cliente de IA acesso somente leitura aos dados da conta em tempo real. Para ajudar seu agente a criar consultas válidas na linguagem de consulta do Google Ads (GAQL), diagnosticar mudanças na performance da conta e gerar código de biblioteca de cliente, use o servidor MCP com estas ferramentas complementares:

• Habilidades do agente da API Google Ads:módulos portáteis de instruções e fluxos de trabalho específicos da API Google Ads, incluindo google-ads-api-mcp-setup, google-ads-api-account-diagnostics e google-ads-api-quickstart, que ensinam seu agente a usar o servidor MCP do Google Ads de forma eficaz com menor sobrecarga de tokens. Instale-os com um único comando (requer o Node.js) ou consulte o guia de habilidades do agente da API Google Ads para as opções Antigravity, Claude Code, Codex e Cursor:

  npx skills add google/skills/skills/ads
  

• Assistente para desenvolvedores da API Google Ads:um plug-in modular para o Google Antigravity e o Claude Code que oferece inspeção de esquema Protobuf local, validação programática de GAQL, geração de código de biblioteca de cliente (incluindo scripts de mutação) e solução de problemas de conversão off-line. Saiba como ele funciona em O que é o Assistente para Desenvolvedores da API Google Ads? ou siga o guia de instalação.

Implantação no Google Cloud

Em vez de hospedar esse servidor MCP localmente, você pode hospedá-lo no Google Cloud Run ou em qualquer outra infraestrutura baseada na nuvem. Isso é útil se você quiser compartilhar o servidor entre diferentes agentes ou executá-lo como um serviço da Web.

Pré-requisitos

1. Um projeto do Google Cloud.

2. A ferramenta de linha de comando gcloud instalada, autenticada e com um projeto ativo configurado:

   gcloud config set project YOUR_PROJECT_ID
   

Criar e enviar uma imagem do Docker

Use o Cloud Build para criar e enviar a imagem para o Artifact Registry sem precisar do Docker instalado localmente.

1. Crie um repositório no Artifact Registry:

   gcloud artifacts repositories create mcp-servers \
     --repository-format=docker --location=us-central1
   

2. Acesse o diretório do projeto:

   cd <full path>/google-ads-mcp
   

3. Crie e envie a imagem:

   gcloud builds submit \
     --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
   

   Essa etapa precisa ser realizada sempre que você quiser atualizar o servidor implantado para a versão mais recente.

Implantar no Google Cloud Run

Defina as variáveis de ambiente necessárias:

• GOOGLE_PROJECT_ID: o ID do projeto do Google Cloud, que tem os níveis de acesso adequados à API.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: o ID do cliente OAuth 2.0 (configurado como um aplicativo da Web no projeto do Google Cloud) para autenticação OAuth no nível do aplicativo. Verifique o seguinte:
  • Você adicionou os URIs de redirecionamento autorizados apropriados para todos os clientes de IA que planeja conectar (como https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect ou https://antigravity.google/oauth-callback).
  • Você adicionou o escopo https://www.googleapis.com/auth/adwords à tela de permissão OAuth em APIs e serviços > Tela de permissão OAuth > Acesso a dados (Adicionar ou remover escopos).
  • Se o status de publicação da tela de permissão OAuth estiver definido como Teste (o padrão), você adicionou as Contas do Google que se conectam ao servidor MCP como Usuários de teste em APIs e serviços > Tela de permissão OAuth > Público (Usuários de teste > + Adicionar usuários).
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: a chave secreta do cliente OAuth correspondente ao ID do cliente OAuth.
• GOOGLE_ADS_MCP_BASE_URL: o URL de base público em que o servidor MCP está acessível (por exemplo, https://google-ads-mcp-xyz-uc.a.run.app). Como o Google Cloud Run gera esse URL durante a implantação inicial, implante sem essa variável primeiro e atualize o serviço após a implantação.
• FASTMCP_HOST: defina como 0.0.0.0 para permitir que o FastMCP aceite conexões de todos os endereços IP.

Implante o serviço no Google Cloud Run:

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

Depois que o Cloud Run concluir a implantação, recupere o URL do serviço atribuído e atualize o serviço com a variável de ambiente GOOGLE_ADS_MCP_BASE_URL:

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

Modelo de autenticação e segurança

A implantação com --allow-unauthenticated desativa a verificação do IAM no nível da infraestrutura do Cloud Run (roles/run.invoker) para que os clientes externos de IA possam se conectar sem precisar de tokens de conta de serviço do Google Cloud. Em vez disso, a autenticação é delegada à camada do aplicativo:

• Quando GOOGLE_ADS_MCP_OAUTH_CLIENT_ID e GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET são fornecidos, o servidor MCP aplica o OAuth 2.0 do Google em todas as solicitações recebidas, desafiando autores de chamadas não autenticados com uma resposta HTTP 401. Todas as solicitações de ferramentas são executadas estritamente com a identidade OAuth do autor da chamada autenticado.
• Omitir --allow-unauthenticated aplica o IAM da infraestrutura do Cloud Run, que exige que os autores de chamadas transmitam tokens de identidade do OIDC do Google Cloud com cada solicitação. Como os clientes de IA padrão (como Claude e ChatGPT) se autenticam usando o OAuth do usuário final em vez de tokens de identidade do IAM do Google Cloud, as conexões diretas dessas plataformas exigem --allow-unauthenticated com o OAuth no nível do aplicativo.

Atenção: nunca omita GOOGLE_ADS_MCP_OAUTH_CLIENT_ID e GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET ao implantar com --allow-unauthenticated. Essas variáveis de ambiente acionam o servidor para alternar do modo stdio local para o transporte streamable-http. Sem eles, o servidor não pode aplicar a autenticação e volta para o Application Default Credentials (ADC), expondo as credenciais da conta de serviço do contêiner a chamadores não autenticados.

Configurar o cliente MCP

Após a implantação, configure o cliente MCP com o URL do Cloud Run. Como o servidor exige autenticação OAuth 2.0, o cliente precisa ser compatível com o fluxo OAuth do MCP ou fornecer um token do portador autorizado:

• Clientes com OAuth:para clientes que oferecem suporte à descoberta de OAuth do MCP (como o Antigravity), a conexão com o endpoint aciona um prompt de autenticação para fazer login com o Google e conceder o escopo https://www.googleapis.com/auth/adwords (listado como .../auth/adwords no console do Google Cloud).
• Plataformas de IA de terceiros (Claude, ChatGPT): nas configurações de conector ou integração do cliente, adicione um conector personalizado que aponte para o URL do Cloud Run com o caminho /mcp (por exemplo, https://your-cloud-run-url.a.run.app/mcp), selecione a autenticação OAuth 2.0 (usando seu próprio ID do cliente OAuth e chave secreta do cliente) e verifique se o URI de callback do cliente foi adicionado aos URIs de redirecionamento autorizados do cliente OAuth. (Os participantes do piloto de endpoint hospedado que estão na lista de permissões também podem consultar o guia de configuração do MCP hospedado.)
• Clientes sem suporte ao OAuth:os clientes que não são compatíveis com fluxos OAuth HTTP vão receber uma resposta HTTP 401 Não autorizado. Para essas ferramentas, use a configuração stdio local.

Exemplo de configuração para um cliente compatível com OAuth (por exemplo, ~/.gemini/settings.json):

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

Recursos principais (ferramentas)

O servidor expõe ferramentas projetadas para descoberta de contas e relatórios de performance:

• list_accessible_customers: retorna a lista de IDs de cliente do Google Ads e nomes de conta acessíveis ao usuário autenticado.
• search: executa solicitações GAQL para buscar métricas, orçamentos e status de recursos.

• get_resource_metadata: recupera metadados sobre um tipo de recurso da API Google Ads, por exemplo, "campaign".

  Isso é útil para entender a estrutura dos dados e quais campos estão disponíveis para consulta.

Observação: essa implementação é somente leitura. Ele não pode modificar lances, pausar campanhas ou criar recursos. Para gerar o código da biblioteca de cliente para operações de mutação, validar consultas GAQL localmente ou inspecionar esquemas Protobuf, use o Assistente para desenvolvedores da API Google Ads. Para configurar o MCP e os fluxos de trabalho de diagnóstico de conta, instale as habilidades do agente da API Google Ads.

Exemplos de comandos para começar

Pergunte o que o servidor pode fazer:

What can the google-ads-mcp server do?

Pergunte sobre os clientes:

What customers do I have access to?

Perguntar sobre campanhas:

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890

Próximas etapas

• Instalar habilidades de agente da API Google Ads
• Aprenda Mais sobre o Assistente para Desenvolvedores da API Google Ads
• Instalar e usar o Assistente para Desenvolvedores da API Google Ads