google-ads-mcp-coolify

Servidor MCP do Google Ads auto-hospedado para Coolify, Docker e qualquer VPS. Transporte HTTP streamable com OAuth 2.0 — conecta Claude Code, Cursor e qualquer cliente MCP à API do Google Ads.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP do Google Ads — Auto-hospedado no Coolify (Docker, HTTP/SSE)

Implante o Servidor MCP do Google Ads no seu próprio VPS com Coolify em 5 minutos. Conecta Claude Code, Claude Desktop, Cursor ou qualquer cliente do Model Context Protocol à API do Google Ads via OAuth 2.0 — via HTTPS, com um endpoint público.

Este repositório é um wrapper Docker pronto para produção em torno de gomarble-ai/google-ads-mcp-server que resolve as duas peças que faltam para implantação remota:

Sem Dockerfile upstream → este repositório adiciona um.
O upstream roda em modo stdio (só funciona localmente com Claude Desktop) → este repositório o envolve com transporte streamable-http para que possa ser acessado pela internet.

Perfeito para equipes que executam infraestrutura MCP auto-hospedada em plataformas como Coolify, Dokploy, EasyPanel, Railway, Render, Fly.io ou qualquer configuração simples de Docker/Kubernetes.

Sumário

Por que auto-hospedar um servidor MCP do Google Ads?
Recursos
Como funciona
Início rápido (Coolify)
Início rápido (Docker simples)
Gerando o credentials.json do OAuth
Conectando a partir do Claude Code / Cursor / Claude Desktop
Ferramentas MCP disponíveis
Notas de segurança
Solução de problemas
Contribuindo
Licença

Por que auto-hospedar um servidor MCP do Google Ads?

Privacidade: seus tokens OAuth do Google Ads nunca saem da sua infraestrutura.
Multi-cliente: uma instância implantada atende Claude Code, Cursor, Continue, Zed, n8n e qualquer outra ferramenta compatível com MCP.
Sem gateway SaaS pago: pule relays MCP de terceiros — vá direto do seu cliente de IA para o seu VPS para a API do Google Ads.
Funciona atrás de proxies reversos: HTTPS via Let's Encrypt, subdomínio personalizado, middleware de autenticação opcional.

Recursos

✅ Transporte HTTP streamable (especificação MCP) — funciona com todos os clientes MCP modernos
✅ OAuth 2.0 com atualização automática — sem rotação manual de tokens
✅ Autenticação Bearer token integrada (MCP_AUTH_TOKEN) — endpoint nunca acessível publicamente por padrão
✅ Credenciais via variáveis de ambiente (GOOGLE_ADS_CREDENTIALS_JSON) — sem necessidade de File Mount no Coolify
✅ Implantação em subdomínio único — https://google-ads-mcp.yourdomain.com/mcp
✅ Suporte multi-conta / MCC via GOOGLE_ADS_LOGIN_CUSTOMER_ID
✅ Construído com FastMCP — rápido, assíncrono, nível de produção
✅ Upstream atualizado: cada build puxa o gomarble-ai/google-ads-mcp-server mais recente de main
✅ Testado no Coolify — também roda em Dokploy, EasyPanel, Railway, Fly.io, Docker simples

Como funciona

┌─────────────────┐       HTTPS         ┌────────────────────────┐       OAuth        ┌──────────────────┐
│  Claude Code /  │ ──── /mcp ─────────▶│  This container        │ ──── refresh ────▶ │  Google Ads API  │
│  Cursor / etc.  │                     │  (FastMCP HTTP server) │                    │  (v19)           │
└─────────────────┘                     └────────────────────────┘                    └──────────────────┘
                                                  │
                                                  ▼
                                        /app/credentials/credentials.json
                                        (mounted as a file by Coolify)

O contêiner faz três coisas na inicialização:

Carrega tokens OAuth de /app/credentials/credentials.json (file mount).
Importa o aplicativo FastMCP definido no server.py upstream.
Executa-o em 0.0.0.0:8000 usando transporte streamable-http.

Início rápido (Coolify)

1. Aponte um subdomínio para o seu VPS

Tipo	Nome	Valor
A	`google-ads-mcp`	`<your VPS IP>`

2. Crie o recurso

Coolify → + Novo Recurso → Repositório Público

Campo	Valor
Repositório	`https://github.com/LuckSigog/google-ads-mcp-coolify`
Branch	`main`
Build Pack	Dockerfile
Localização do Dockerfile	`/Dockerfile`
Porta Exposta	`8000`
Domínio	`https://google-ads-mcp.yourdomain.com`

3. Variáveis de Ambiente

GOOGLE_ADS_DEVELOPER_TOKEN=<your_developer_token>
GOOGLE_ADS_AUTH_TYPE=oauth
PORT=8000

# Paste the full credentials.json content (single line is fine, JSON parser handles it)
GOOGLE_ADS_CREDENTIALS_JSON={"token":"ya29...","refresh_token":"1//0h...","token_uri":"https://oauth2.googleapis.com/token","client_id":"...","client_secret":"...","scopes":["https://www.googleapis.com/auth/adwords"]}

# Bearer token for endpoint auth (RECOMMENDED — without it, your endpoint is public)
# Generate with: python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
MCP_AUTH_TOKEN=<long_random_string>

# Optional — only if you use a Manager (MCC) account:
# GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890

⚠️ Não defina NODE_ENV ou qualquer variável de ambiente não relacionada — o Coolify injeta todas as variáveis de ambiente como ARGs de build, o que pode quebrar builds não relacionados.

4. (Opcional) Monte as credenciais OAuth como um arquivo

Você pode pular isso completamente se definir GOOGLE_ADS_CREDENTIALS_JSON acima. Use um File Mount apenas se preferir manter o JSON fora das variáveis de ambiente:

Coolify → Armazenamentos → + Adicionar → File Mount

Caminho de Montagem	Conteúdo
`/app/credentials/credentials.json`	Cole todo o JSON gerado abaixo

5. Implante

Clique em Implantar. Quando o contêiner estiver saudável:

curl -i https://google-ads-mcp.yourdomain.com/mcp
# Expected: HTTP 200, 405, or similar — NOT 502

Início rápido (Docker simples)

docker build -t google-ads-mcp .

docker run -d \
  --name google-ads-mcp \
  -p 8000:8000 \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your_token \
  -e GOOGLE_ADS_AUTH_TYPE=oauth \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/app/credentials/credentials.json \
  -v $(pwd)/credentials.json:/app/credentials/credentials.json:ro \
  google-ads-mcp

Gerando o OAuth `credentials.json`

Você só executa isso uma vez na sua máquina local para inicializar o refresh token. O contêiner atualizará os tokens de acesso automaticamente a partir de então.

Pré-requisitos

Vá para o Google Cloud Console
Crie um ID de cliente OAuth 2.0 do tipo Aplicativo de desktop
Baixe o arquivo client_secret_*.json
Certifique-se de que a API do Google Ads esteja ativada no projeto
Tenha um Token de desenvolvedor do Google Ads (solicite aqui)

Execute o script de inicialização

# gen_credentials.py
from google_auth_oauthlib.flow import InstalledAppFlow
import json, glob, sys

matches = glob.glob('client_secret*.json')
if not matches:
    sys.exit("Place a client_secret*.json next to this script first.")

flow = InstalledAppFlow.from_client_secrets_file(
    matches[0], scopes=['https://www.googleapis.com/auth/adwords'])
creds = flow.run_local_server(port=0)

with open('credentials.json', 'w') as f:
    json.dump({
        'token': creds.token,
        'refresh_token': creds.refresh_token,
        'token_uri': creds.token_uri,
        'client_id': creds.client_id,
        'client_secret': creds.client_secret,
        'scopes': creds.scopes,
    }, f, indent=2)
print("OK -> credentials.json generated")

python3 -m venv .venv && source .venv/bin/activate
pip install google-auth-oauthlib
python3 gen_credentials.py

Um navegador será aberto. Entre com a conta do Google que tem acesso à sua conta do Google Ads e autorize. Você obterá um credentials.json no diretório atual.

Envie esse JSON como um File Mount no Coolify (passo 4 acima).

Conectando a partir do Claude Code / Cursor / Claude Desktop

Claude Code (CLI)

Se você definir MCP_AUTH_TOKEN:

claude mcp add --transport http google-ads https://google-ads-mcp.yourdomain.com/mcp \
  --header "Authorization: Bearer YOUR_MCP_AUTH_TOKEN" --scope user
claude mcp list

Sem autenticação:

claude mcp add --transport http google-ads https://google-ads-mcp.yourdomain.com/mcp --scope user

Teste:

"List my Google Ads accounts"

Cursor / Continue / Zed

Adicione à configuração dos seus servidores MCP:

{
  "mcpServers": {
    "google-ads": {
      "type": "http",
      "url": "https://google-ads-mcp.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

Claude Desktop (somente stdio local)

O Claude Desktop não fala HTTP MCP. Se você quiser usá-lo lá, instale o gomarble-ai/google-ads-mcp-server upstream diretamente na sua máquina.

Ferramentas MCP disponíveis

Herdadas do upstream:

Ferramenta	Descrição
`list_accounts`	Lista todas as contas do Google Ads acessíveis, incluindo subcontas aninhadas sob MCC
`run_gaql`	Executa qualquer consulta da Google Ads Query Language (GAQL) — campanhas, grupos de anúncios, palavras-chave, conversões, relatórios
`run_keyword_planner`	Gera ideias de palavras-chave com volume de pesquisa, concorrência e faixa de lance de CPC

A referência GAQL é exposta como um recurso MCP: gaql://reference.

Notas de segurança

Este wrapper vem com autenticação Bearer token integrada (variável de ambiente MCP_AUTH_TOKEN). Defina-a e o endpoint exigirá Authorization: Bearer <token> em cada requisição — sem token, sem acesso.

Gere um token forte:

python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
# or:
openssl rand -base64 32

Para implantações em equipe, vale considerar endurecimento adicional:

Tokens por usuário com revogação — apoie o middleware com uma tabela de hashes de tokens no Supabase/Postgres (planejado em uma versão futura; PRs são bem-vindos)
Cloudflare Access / Tailscale / WireGuard — SSO zero-trust na frente do endpoint
Lista de permissão de IP na camada Coolify/Cloudflare se conectar a partir de um conjunto fixo de máquinas

Mesmo com MCP_AUTH_TOKEN, trate o endpoint como uma fronteira de defesa em profundidade, não a única linha de defesa — rotacione o token periodicamente.

Solução de problemas

`sh: tsc: not found` ou build falha com devDependencies ausentes

Você está esbarrando na peculiaridade do Coolify de variável de ambiente como ARG de build. Não defina NODE_ENV=production como variável de ambiente no serviço Coolify. Isso é injetado como ARG de build e quebra Dockerfiles não relacionados. (Este repositório é Python, mas o mesmo padrão afeta servidores MCP baseados em Node.)

`ERROR: failed to read dockerfile`

Verifique Base Directory = / e Dockerfile Location = /Dockerfile na aba de Configuração do Coolify.

`401 Unauthorized` / `OAuth credentials expired`

Abra credentials.json e confirme se refresh_token está presente. Se estiver ausente, regenere via gen_credentials.py e reenvie o file mount.

`Developer token is not approved`

Um token de desenvolvedor novo tem acesso limitado (somente contas de teste). Para contas de produção, solicite Acesso Básico no Centro da API do Google Ads.

`LOGIN_CUSTOMER_ID required`

Você está consultando por meio de uma conta de Gerente (MCC). Defina GOOGLE_ADS_LOGIN_CUSTOMER_ID=<mcc_id_without_dashes> e reimplante.

`502 Bad Gateway` após a implantação

O contêiner iniciou, mas não está escutando na porta 8000. Verifique os logs de build — na maioria das vezes o git clone do upstream falhou. Reexecute a implantação.

Contribuindo

PRs são bem-vindos. Especificamente úteis:

Middleware de autenticação opcional (Bearer / Basic / lista de permissão de IP)
Opção de SHA upstream fixado (atualmente compila contra main)
Helm chart / manifestos Kubernetes
Exemplos para integrações MCP com n8n, Make, Zapier

Licença

MIT — mesma licença do projeto gomarble upstream.

Créditos

Servidor MCP upstream: gomarble-ai/google-ads-mcp-server
Model Context Protocol: modelcontextprotocol.io
Coolify: coolify.io
FastMCP: jlowin/fastmcp

Palavras-chave: google ads mcp server, google ads mcp coolify, self-hosted mcp google ads, mcp server docker, deploy mcp server vps, claude code google ads integration, fastmcp http server, google ads api claude, mcp streamable http, model context protocol google ads, cursor google ads mcp, n8n google ads mcp, self host model context protocol, google ads oauth mcp.