MCP Google Ads
EN Conectar
MCP Google Ads

Model Context Protocol · Google Ads API v24+

Comande o Google Ads
direto pelo Claude.

Um servidor MCP que liga o Claude às suas contas Google Ads — leitura, relatórios, pesquisa de keywords e criação de campanhas de Search, com login OAuth embutido. Status: LIVE.

Conectar agora Ver o que ele faz

37 tools · OAuth embutido · multi-tenant · grátis

REST httpx · sem gRPC Arquitetura hexagonal Writes nascem PAUSED Leituras via GAQL validateOnly dry-run Multi-tenant na Vercel OAuth Authorization Server REST httpx · sem gRPC Arquitetura hexagonal Writes nascem PAUSED Leituras via GAQL validateOnly dry-run Multi-tenant na Vercel OAuth Authorization Server
O que é

Seu Google Ads, operado em linguagem natural

O MCP Google Ads é um servidor Model Context Protocol que dá ao Claude acesso real às suas contas — não um chatbot que adivinha, mas chamadas tipadas na Google Ads API REST (v24+).

Conexão real

Claude fala com a sua conta

Liste campanhas, puxe relatórios de gasto e conversão, pesquise keywords e crie campanhas de Search — tudo conversando com o Claude. O login do Google é OAuth2, embutido no fluxo.

Arquitetura

Hexagonal, ports-and-adapters

Domínio, aplicação e infraestrutura separados; cliente httpx async puro, sem gRPC. O mesmo core roda local em stdio (single-tenant) ou multi-tenant na Vercel.

Status

LIVE em produção

Deploy multi-tenant em gamcp.vercel.app — tokens no Supabase, cache no Upstash, e nós somos o OAuth Authorization Server. O modo local guarda o refresh token num arquivo 0600.

O que ele já faz

O catálogo completo de ferramentas

37 tools agrupadas por função — da autenticação aos relatórios GAQL, da pesquisa de keywords ao funil de Search que nasce pausado. Tudo abaixo já está implementado e no ar.

Autenticação

4 tools
  • google_loginConecta uma conta Google (consentimento no browser); guarda o refresh token.
  • google_submit_callbackFinaliza o login submetendo a URL de callback redirecionada.
  • google_token_statusDiz se a credencial guardada é válida, seus escopos e expiração.
  • google_refresh_tokenGera um access token novo a partir do refresh token guardado.

Leituras & relatórios (GAQL)

11 tools
  • list_accessible_customersLista as contas Google Ads que a credencial acessa.
  • list_campaignsLista campanhas de uma conta.
  • list_ad_groupsLista grupos de anúncios.
  • list_adsLista anúncios.
  • get_insightsRelatório síncrono: gasto, impressões, cliques, conversões.
  • run_insights_reportRelatório maior sobre um intervalo de datas.
  • get_search_termsTermos de pesquisa que dispararam os anúncios.
  • get_recommendationsRecomendações de otimização do Google, com filtro por tipo.
  • generate_keyword_ideasPesquisa de keywords: volume, concorrência, lances.
  • list_conversion_actionsLista as ações de conversão da conta.
  • get_conversion_tagsRecupera os snippets (gtag / event) de uma conversão.

Writes — funil de Search

6 · nascem PAUSED
  • create_campaign_budgetCria um orçamento diário (em unidades de moeda).
  • create_campaignCria uma campanha de Search ligada a um orçamento.
  • create_ad_groupCria um grupo de anúncios sob a campanha.
  • add_keywordsAdiciona keywords a um grupo de anúncios.
  • create_responsive_search_adCria um RSA (3–15 títulos ≤30 / 2–4 descrições ≤90).
  • create_search_campaignComposto: orçamento → campanha → grupo → targeting → keywords → RSA numa só chamada.

Writes — targeting & negativos

3 tools
  • add_geo_targetingAdiciona critérios de geolocalização a uma campanha.
  • add_age_targetingAdiciona critérios de faixa etária a um grupo de anúncios.
  • add_negative_keywordsAdiciona keywords negativas no nível de campanha ou grupo.

Writes — extensions (assets)

5 tools
  • create_sitelinksAnexa assets de sitelink a uma campanha.
  • create_calloutsAnexa assets de callout (≤25 caracteres cada).
  • create_structured_snippetAnexa um structured snippet (header + valores).
  • create_callAnexa um asset de chamada (telefone + região).
  • create_promotionAnexa um asset de promoção.

Writes — conversões, status & recs

6 · confirm=true
  • create_conversion_actionCria uma ação de conversão (devolve os snippets de tag).
  • update_campaign_statusAtiva/pausa/arquiva uma campanha (destrutivo, precisa de confirm).
  • pause_campaignPausa uma campanha (destrutivo, precisa de confirm).
  • update_ad_group_statusAtiva/pausa/arquiva um grupo (destrutivo, precisa de confirm).
  • update_ad_statusAtiva/pausa/arquiva um anúncio (destrutivo, precisa de confirm).
  • apply_recommendationsAplica recomendações do Google por resource name (precisa de confirm).

Há também um prompt MCP analyze_account_performance para relatórios guiados.

Modelo de segurança dos writes

O Claude não gasta seu dinheiro sozinho

Escrever no Google Ads mexe com dinheiro real. Por isso cada write passa por barreiras explícitas — você está sempre no controle do que vira gasto.

Criações nascem PAUSED

Nada gasta até você ativar explicitamente. Toda campanha, grupo e anúncio criado já vem pausado.

Status exige confirm=true

Mudar status é destrutivo. Sem confirm, a tool devolve um preview e não faz nenhuma chamada HTTP.

preview=true = dry-run

Roda um validateOnly server-side: valida a operação sem persistir nada. Cheque antes de executar de verdade.

Sem auto-rollback

O funil é não-atômico: se falhar no meio, devolve os recursos já criados (PAUSED) e onde parou — não apaga nada sozinho.

Dinheiro em unidades

Orçamentos vêm em unidades de moeda (20.0 = R$20/dia) e são convertidos para micros no use case. Sem confusão de centavos.

Whitelist de escopos

A credencial só acessa o que você autorizou no consentimento OAuth — e o google_token_status mostra exatamente quais escopos estão ativos.

Como conectar

Em pé em poucos minutos

Dois caminhos: o hospedado (recomendado, zero setup) e o local stdio (para devs single-tenant). Os dois terminam no mesmo lugar — o Claude operando sua conta.

Recomendado

Hospedado — gamcp.vercel.app

Adicione o servidor MCP como connector no Claude e faça login. Nada para instalar; nós cuidamos do developer token e dos tokens OAuth.

  1. Adicione o connector. No Claude.ai → Configurações → Conectores → Adicionar conector personalizado, cole a URL do servidor MCP. No Claude Code, use o comando abaixo.
    # Claude Code
claude mcp add --transport http \
  google-ads https://gamcp.vercel.app
  2. Faça login no Google. Rode a tool google_login — abre o consentimento no browser e guarda seu refresh token com segurança.
  3. Confirme. Rode google_token_status para validar a credencial e list_accessible_customers para ver suas contas. Pronto para operar.
Avançado

Local stdio — single-tenant

Rode o servidor na sua máquina. O refresh token fica num arquivo 0600 local; você usa seu próprio developer token da MCC.

  1. Instale. Crie o ambiente e instale as dependências.
    python -m venv venv
venv/bin/pip install -e ".[dev]"
cp .env.example .env.local
  2. Configure as credenciais. Preencha .env.local: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_ADS_DEVELOPER_TOKEN e NGROK_URL (túnel público para o callback OAuth).
  3. Rode e logue. Suba o servidor e conecte sua conta.
    PYTHONPATH=src venv/bin/python \
  -m mcp_google_ads
# depois, no Claude: google_login

Perguntas frequentes

Ficou alguma dúvida? Escreva para bruno@b2tech.io.

Quanto custa?
O MCP Google Ads é grátis. Você só precisa de uma conta Google Ads e, no modo local, de um developer token da sua MCC.
É seguro? O Claude pode gastar dinheiro sozinho?
Não. Toda criação nasce PAUSED — nunca gasta até você ativar explicitamente. Mudanças de status são destrutivas e exigem confirm=true; sem confirm, a ferramenta só devolve um preview e não faz nenhuma chamada HTTP.
Preciso de developer token?
No modo local stdio, sim — vem da API Center da sua MCC do Google Ads. No deploy hospedado (gamcp.vercel.app) o token de plataforma já está configurado; você só faz o login OAuth da sua conta.
Multi-tenant — onde ficam meus tokens?
No deploy hospedado, os refresh tokens ficam no Supabase e o cache no Upstash; nós somos o OAuth Authorization Server. No modo local, o refresh token fica num arquivo 0600 na sua máquina (single-tenant).
Quais contas eu consigo acessar?
As contas que a credencial logada pode acessar. O list_accessible_customers lista todas, e o manager/login-customer é resolvido automaticamente por credencial no google_login.
O que é o preview=true?
É um dry-run server-side (validateOnly): valida a operação sem persistir nada. Útil para checar um write antes de executá-lo de verdade.
Local ou hospedado — qual escolher?
Hospedado (gamcp.vercel.app) é o caminho rápido: zero setup, é só adicionar como connector no Claude e logar. Local stdio é single-tenant, para devs que querem rodar tudo na própria máquina com o refresh token num arquivo 0600.
Comece agora

Pare de alternar entre abas.
Peça ao Claude e ele opera o Google Ads.

Leitura, relatórios, keyword research e campanhas de Search — com OAuth embutido e writes que nascem pausados. Grátis e no ar.

Conectar agora Rever as ferramentas

37 tools · OAuth2 embutido · multi-tenant na Vercel