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 os 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 os agentes de IA analisem e recuperem dados de campanha 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 conexã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)
  • Idioma:Python
  • Transporte:entrada/saída padrão (stdio)
  • Autenticação:OAuth 2.0 ou conta de serviço

Como funciona o loop 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, verifique se você tem as seguintes credenciais do Console de desenvolvedores do Google Ads:

  • Token de desenvolvedor:sua string de acesso exclusiva de 22 caracteres.
  • ID do projeto:o identificador do seu projeto na nuvem do Google Cloud.
  • Credenciais OAuth:um par de ID do cliente/chave secreta do cliente OAuth2 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. Consulte a documentação do host para saber o local e o nome exatos desse arquivo de configuração.

JSON

{
  "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

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. 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 pelo ID do projeto no Google Cloud.
  • GOOGLE_ADS_DEVELOPER_TOKEN: o token de desenvolvedor que você quer que o servidor MCP use.
  • 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 do MCP está acessível. Ele será 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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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 cliente 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 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