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 campanhas usando linguagem natural.

Recursos e suporte da comunidade

Visão geral técnica

Ao implementar esse servidor MCP, você elimina a necessidade de 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 transmitível (streamable-http / Cloud Run)
  • Autenticação:OAuth 2.0 ou conta de serviço

Como o loop de interação funciona

  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 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, verifique se você tem as seguintes credenciais do Google Cloud console:

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 e o nome exatos desse arquivo de 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 do Docker

Você pode usar o Cloud Build para criar e enviar a imagem ao 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 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 2.0 (configurado como um aplicativo da Web no seu projeto do Google Cloud) para autenticação OAuth no nível do aplicativo. Verifique se:
    • Você adicionou os URIs de redirecionamento autorizados adequados 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ê terá adicionado 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-alvo (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 pode ser acessado (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 de 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 de IAM no nível da infraestrutura do Cloud Run (roles/run.invoker), para que os clientes de IA externos possam se conectar sem precisar de tokens de conta de serviço do Google Cloud. 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 a todas as solicitações recebidas, desafiando os autores de chamadas não autenticados com uma resposta HTTP 401. Todas as solicitações de ferramentas são executadas estritamente na 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 OIDC do Google Cloud com cada solicitação. Como os clientes de IA padrão (como Claude e ChatGPT) são autenticados 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.

Configurar o cliente MCP

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

  • Clientes com OAuth ativado:para clientes que oferecem suporte à descoberta do 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 da lista de permissões do piloto de endpoint hospedado também podem consultar o guia de configuração do MCP hospedado.
  • Clientes sem suporte ao OAuth:os clientes que não oferecem suporte a fluxos OAuth HTTP vão receber uma resposta HTTP 401 não autorizada. Para essas ferramentas, use a configuração stdio local em vez disso.

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 clientes e nomes de contas do Google Ads 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 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