MCP Google Ads

mcp-google-ads

Servidor MCP do Google Ads multi-contas para operadores que precisam de uma única superfície MCP em várias contas de clientes ou contas de anúncios internas sem reiniciar o servidor.

Postura de lançamento: pacote beta, versão 0.1.0 de pyproject.toml.

Escolha seu caminho

Você é...	Comece aqui	Depois
Conectando o servidor ao seu cliente MCP	docs/start-here.md	Início rápido abaixo
Auditando troca de contas e tentativas	docs/architecture.md	gads/server.py
Revisando metadados de empacotamento	pyproject.toml	accounts.example.json

Arquitetura

flowchart TD
  U[AI operator] --> C[MCP client]
  C --> S[FastMCP server]
  S --> M[Account manager]
  M --> F[Accounts config]
  S --> Q[GAQL query helpers]
  Q --> R[Retry wrapper]
  R --> A[Google Ads API]
  A --> R --> S

Fluxo de requisições

flowchart TD
  P[Operator asks for account or campaign data] --> T[Selected MCP tool]
  T --> A[Resolve named or default account]
  A --> B[Build Google Ads client]
  B --> C[Run GAQL query]
  C --> D{API call succeeds?}
  D -- yes --> E[Normalize rows and return]
  D -- retryable --> F[Backoff and retry]
  F --> D
  D -- no --> G[Return error payload]

Início rápido

1. Instale o pacote.

python -m pip install mcp-google-ads-multi

2. Copie o modelo de configuração de contas e adicione suas contas.

mkdir -p ~/.config/mcp-google-ads
cp accounts.example.json ~/.config/mcp-google-ads/accounts.json

3. Registre-o no seu cliente MCP.

{
  "mcpServers": {
    "google-ads": {
      "command": "uvx",
      "args": ["mcp-google-ads-multi"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_ACCOUNTS_CONFIG": "/Users/you/.config/mcp-google-ads/accounts.json"
      }
    }
  }
}

Ferramentas disponíveis

Grupo de ferramentas	Ferramentas	Finalidade
Seleção de conta	list_accounts, set_default_account, list_customers	Gerenciar roteamento de contas e descobrir clientes acessíveis
Resumo de gastos	get_account_summary, compare_periods	Relatórios de conta por período
Análise de campanhas	list_campaigns, get_campaign_performance	Inventário de campanhas e métricas baseadas em intervalo
Detalhes no nível de consulta	get_keyword_performance, search_terms_report, get_ad_performance	Relatórios de palavras-chave, termos de pesquisa e anúncios

Prova em tempo de execução

Afirmação	Prova
O ponto de entrada do pacote é estável	mcp-google-ads-multi = "gads.server:main" em pyproject.toml
Roteamento multi-contas é de primeira classe	AccountManager() e set_default_account() em gads/server.py
Consultas passam por auxiliares reutilizáveis	gads/query.py e gads/retry.py
Configuração é orientada por arquivo	accounts.example.json documenta a estrutura de contas

Mapa do repositório

Caminho	Finalidade
gads/server.py	Superfície de ferramentas FastMCP
gads/accounts.py	Configuração de contas, carregamento de OAuth/conta de serviço
gads/query.py	Auxiliares de execução GAQL
gads/retry.py	Comportamento de tentativas para chamadas de API
docs/start-here.md	Configuração, validação, falhas comuns
docs/architecture.md	Mapa de componentes e ciclo de vida de requisições

Validação

Verificação	Comando
Importação compila	python -m compileall gads
Pacote compila	python -m build
Links de README/docs são locais	rg '\\]\\(([^)]+\\.md)\\)' README.md docs/

Licença

MIT

Contexto do projeto para novas tarefas

Leia prompt.md, depois INDEX.md, para decisões específicas do projeto, rotas de tarefas e handoff atual. Exemplos históricos não selecionam a tarefa atual.