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 oferece uma ponte padronizada para a API Google Ads, que permite que agentes de IA analisem e recuperem dados de campanha usando linguagem natural.

Recursos e suporte da comunidade

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

  Use a guia "Problemas" 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ê elimina a necessidade de escrever um "código de ligação" 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/saída padrão (stdio) ou HTTP/SSE (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 subjacente 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, confira 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). Consulte 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. Observação: os tokens de desenvolvedor (GOOGLE_ADS_DEVELOPER_TOKEN) foram desativados 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 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 do 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"
      }
    }
  }
}

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 Docker

Você pode usar o Cloud Build para criar e enviar a imagem ao Artifact Registry sem precisar instalar o Docker 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 seu projeto do Google Cloud, que tem os níveis de acesso à API adequados.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: o ID do cliente OAuth que você quer que o servidor MCP use.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: a chave secreta do cliente OAuth que você quer que o servidor MCP use.
• GOOGLE_ADS_MCP_BASE_URL: o URL base em que o servidor MCP está acessível. Ele é atribuído automaticamente pelo Google Cloud Run após a primeira implantação. É possível atualizar as variáveis de ambiente 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.

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,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

Configurar o cliente MCP

Após a implantação, atualize a configuração do cliente MCP (por exemplo, ~/.gemini/settings.json) para usar o URL do Cloud Run.

{
  "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 clientes do Google Ads e nomes de contas acessíveis ao usuário autenticado.
• search: executa solicitações da linguagem de consulta do Google Ads (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.

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?

Pergunte 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