google-measurement-mcp

google-measurement-mcp

A stack de medição do Google para agentes de IA — GA4, Search Console e Tag Manager em um único servidor MCP.

As ferramentas de leitura estão sempre ativas. As ferramentas de escrita estão desativadas, a menos que você as habilite explicitamente. Operações destrutivas não são implementadas de forma alguma.

Status: Início — v0.1.0. 15 ferramentas de leitura e 9 ferramentas de escrita opcionais estão disponíveis em GA4, Search Console e Tag Manager. Veja Roadmap.

Por que isso existe

Apontar um agente de IA para suas análises é de baixo risco. Apontar um para o seu container ativo do Tag Manager não é — uma publicação ruim quebra o rastreamento em todas as páginas do seu site.

A maioria dos servidores MCP do GTM pode publicar containers. Este torna isso difícil de propósito:

• As ferramentas de escrita estão ausentes, a menos que você passe --enable-write. Não é "presente e com erro" — genuinamente não está na lista de ferramentas, então um agente não pode vê-las ou tentar usá-las.
• Operações destrutivas não existem no código. Sem exclusão, sem arquivamento, sem remoção de tags, gatilhos, variáveis, sitemaps ou eventos-chave. Esta é uma escolha de design deliberada, não uma lacuna.
• A publicação exige confirmação humana. gtm_publish_version sem confirm: true retorna um diff do que iria ao ar e se recusa a publicar.

Você deve usar este ou o servidor oficial do Google?

Se você só precisa de GA4, e apenas leituras — use o do Google. Ele é mantido pelo Google, tem uma comunidade muito maior e possui recursos de GA4 que este servidor não tem.

Onde o do Google é genuinamente melhor: fluxos de trabalho apenas com GA4, análise de funil, atribuição do Google Ads e o simples fato de ser mantido pela equipe que possui a API. Se sua pergunta é "o que aconteceu na minha propriedade GA4", use o deles primeiro.

Onde este ganha seu lugar: você precisa do Search Console e do Tag Manager junto com o GA4 sem executar três servidores, ou precisa de acesso de escrita e quer que as operações perigosas sejam difíceis de alcançar por acidente. Executar ambos lado a lado é totalmente razoável — eles não entram em conflito.

Início rápido (cerca de 5 minutos)

1. Crie um projeto no Google Cloud e ative as APIs

No console do Google Cloud, crie um projeto e ative:

• Google Analytics Data API
• Google Analytics Admin API
• Google Search Console API
• Tag Manager API

2. Configure a tela de consentimento

APIs e serviços → Tela de consentimento OAuth. O Google migrou isso para o Google Auth Platform, onde as configurações estão divididas nas páginas da barra lateral — Branding, Público, Clientes, Acesso a dados. Defina o tipo de usuário como Externo e seu e-mail como ambos os contatos.

Não nomeie o aplicativo como google-measurement-mcp. O Google rejeita qualquer nome de aplicativo OAuth que contenha "Google" com uma mensagem que não explica o motivo: "A solicitação falhou porque o nome do aplicativo não está em conformidade com os requisitos do Google."

Nomeie-o como Measurement MCP em vez disso. É apenas o rótulo na sua própria tela de consentimento e não tem nada a ver com o nome do pacote.

3. ⚠️ Publique o aplicativo — não pule esta etapa

Google Auth Platform → Público → Publicar aplicativo. (UI antiga: Tela de consentimento OAuth → Status de publicação.)

Se você deixar o status como Testando, o Google expira seu login após 7 dias e você terá que entrar novamente toda semana.

Publicar não é verificação do Google. Você é o único usuário do seu próprio cliente OAuth, então não há revisão, nenhuma auditoria de segurança e nenhuma espera. Você verá uma tela única de "O Google não verificou este aplicativo" — isso é esperado. Clique em Avançado → Ir para (não seguro). É o seu próprio aplicativo.

4. Crie um cliente OAuth

Google Auth Platform → Clientes → Criar cliente OAuth → Tipo de aplicativo: Aplicativo para desktop. (UI antiga: APIs e serviços → Credenciais → Criar credenciais → ID do cliente OAuth.)

Anote o ID e o segredo do cliente. Aplicativo para desktop é importante — um cliente de "aplicativo da web" falha com redirect_uri_mismatch.

5. Configure seu cliente MCP

claude mcp add google-measurement \
  --scope user \
  -e GMCP_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com \
  -e GMCP_OAUTH_CLIENT_SECRET=your-client-secret \
  -- npx -y google-measurement-mcp

{
  "mcpServers": {
    "google-measurement": {
      "command": "npx",
      "args": ["-y", "google-measurement-mcp"],
      "env": {
        "GMCP_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GMCP_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

{
  "mcpServers": {
    "google-measurement": {
      "command": "npx",
      "args": ["-y", "google-measurement-mcp"],
      "env": {
        "GMCP_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GMCP_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

6. Entre uma vez

Execute o servidor uma vez em um terminal. Ele imprime uma URL — abra, aprove, pronto. O token de atualização é armazenado em cache em ~/.config/google-measurement-mcp/ com permissões somente do proprietário, e seu cliente MCP o utiliza a partir de então.

GMCP_OAUTH_CLIENT_ID=... GMCP_OAUTH_CLIENT_SECRET=... npx -y google-measurement-mcp

Nenhuma concessão de permissão é necessária no GA4, Search Console ou Tag Manager. O OAuth usa o acesso que sua conta do Google já possui.

Ativando ferramentas de escrita

As ferramentas de escrita estão ocultas por padrão. Para expô-las:

{
  "mcpServers": {
    "google-measurement": {
      "command": "npx",
      "args": ["-y", "google-measurement-mcp", "--enable-write"],
      "env": { "GMCP_ENABLE_WRITE": "1" }
    }
  }
}

A flag ou a variável de ambiente é suficiente. Na inicialização, o servidor escreve uma linha no stderr nomeando cada ferramenta de escrita que expôs.

O modo de escrita solicita escopos OAuth adicionais, então você deve entrar novamente após ativá-lo.

Configuração alternativa: conta de serviço (agências e CI)

Use isso quando precisar de operação headless, trabalhos agendados ou uma identidade em muitas propriedades de clientes. É mais trabalho — exige conceder acesso em três UIs de produtos separadas.

{
  "mcpServers": {
    "google-measurement": {
      "command": "npx",
      "args": ["-y", "google-measurement-mcp"],
      "env": { "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json" }
    }
  }
}

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,\
https://www.googleapis.com/auth/webmasters.readonly,\
https://www.googleapis.com/auth/tagmanager.readonly

Ordem de resolução de credenciais

1. GOOGLE_APPLICATION_CREDENTIALS — conta de serviço, se definida
2. Token OAuth de usuário em cache
3. Credenciais padrão do aplicativo

A linha de inicialização no stderr informa qual foi resolvida.

Configuração

Ferramentas

Leitura — sempre disponíveis (15)

As respostas são limitadas a 25 linhas por padrão. Quando a saída é cortada, você recebe truncated: true mais orientação — prefira estreitar a consulta em vez de aumentar limit.

Escrita — apenas com --enable-write (9)

gtm_update_tag mescla — omissão preserva, vazio explícito limpa.

A API bruta do GTM substitui: omitir firingTriggerId o esvazia silenciosamente, deixando uma tag que parece completamente normal na UI do GTM e nunca dispara. Verificamos isso contra a API ativa e depois fizemos este servidor ler-e-mesclar para que isso não possa acontecer por acidente.

// changes the name, keeps everything else
{ "tagPath": "...", "name": "New name", "type": "html" }

// deliberately unwires the tag from all triggers
{ "tagPath": "...", "name": "New name", "type": "html", "firingTriggerId": [] }

parameter mescla por chave, então você pode alterar um parâmetro sem reenviar o restante. A resposta lista preservedFields para que você veja o que foi mantido.

Segurança

Não implementado, por design:

delete_key_event · archive_custom_dimension · delete_sitemap · exclusão de tag / gatilho / variável · adição e remoção de site no GSC · mutação de propriedade e fluxo de dados no GA4

Estes são omitidos deliberadamente. Um agente não pode chamar o que não existe.

Também:

• As escritas do GTM operam em um espaço de trabalho, nunca diretamente no container ativo.
• O GTM mantém histórico de versões, então uma publicação pode ser revertida pela UI do GTM.

O portão de confirmação de publicação

gtm_publish_version é a única operação aqui que altera um site ativo. Ela exige confirm: true.

Chamada sem isso, a ferramenta executa uma execução seca: ela busca a versão que iria ao ar, faz o diff contra a versão atualmente ativa e retorna um resumo — nomeando tags, gatilhos e variáveis adicionados ou removidos. Ela não publica nada.

// confirm omitted -> nothing published
{
  "published": false,
  "dryRun": true,
  "wouldPublish": { "containerVersionId": "7", "tagCount": 3 },
  "currentlyLive": { "containerVersionId": "6", "tagCount": 3 },
  "delta": { "tags": { "added": ["Tag NEW"], "removed": ["Tag GONE"], "unchangedCount": 2 } },
  "instruction": "NOTHING WAS PUBLISHED. Show this summary to a human..."
}

Isto é verificado por um teste de espionagem que afirma que a API de publicação nunca é invocada sem confirm: true — inclusive quando confirm é um valor não booleano verdadeiro como "true" ou 1, que a validação rejeita:

node scripts/verify-confirm-gate.mjs

Solução de problemas

"O nome do aplicativo não está em conformidade com os requisitos do Google" O nome do seu aplicativo OAuth contém "Google", o que a política de marca do Google proíbe. Renomeie-o para Measurement MCP. Isso é apenas um rótulo de exibição da tela de consentimento e não tem relação com o nome do pacote.

"Seu login do Google salvo não é mais válido" Provavelmente sua tela de consentimento ainda está em Teste (expiração do token em 7 dias) — consulte etapa 3. Outras causas: mais de 25 logins salvos para um único cliente OAuth, relógio fora de sincronia ou acesso revogado na página da sua conta do Google.

redirect_uri_mismatch Seu cliente OAuth é do tipo "Aplicativo da web". Crie um cliente Aplicativo de desktop em vez disso.

"Permissão negada" A identidade conectada não tem acesso a essa propriedade, site ou contêiner — ou a API relevante não está ativada no seu projeto Cloud. No caminho da conta de serviço, confirme que todas as três concessões foram feitas.

Uma API funciona, mas outra não retorna nada (por exemplo, GA4 funciona, Tag Manager vazio) Seus ativos de GA4, Search Console e Tag Manager provavelmente estão divididos entre diferentes contas do Google. gtm_list_accounts retornando 0 em vez de um erro é o sinal — a chamada foi bem-sucedida, simplesmente não havia nada que aquela identidade pudesse ver.

Não reautentique como a outra conta. Isso geralmente apenas move o problema, perdendo o acesso às APIs que funcionam atualmente. Em vez disso, conceda à sua identidade existente acesso ao ativo ausente:

• Tag Manager → Administrador → Gerenciamento de usuários → adicione seu e-mail
• GA4 → Administrador → Gerenciamento de acesso à propriedade → adicione seu e-mail
• Search Console → Configurações → Usuários e permissões → adicione seu e-mail

Não é necessária reautenticação; os escopos já estão concedidos. As alterações de permissão levam um ou dois minutos para serem propagadas.

"Cota do Google esgotada" A inspeção de URL do Search Console tem limite de 2.000/dia e 600/minuto por propriedade. A API do Tag Manager tem limites estritos por usuário — as chamadas GTM são espaçadas em minutos, não segundos.

Ferramentas de escrita ausentes Esperado, a menos que você tenha passado --enable-write ou definido GMCP_ENABLE_WRITE=1. Reautentique após ativar, pois o modo de escrita precisa de escopos adicionais.

Roteiro

• Fase 1 — autenticação, servidor, ga4_run_report
• Fase 2 — suíte completa de leitura em GA4, Search Console, Tag Manager
• Fase 3 — ferramentas de escrita atrás do sinalizador, porta de confirmação de publicação
• Fase 4 — testes de contrato, matriz de rastreabilidade, CI
• Fase 5 — lançamento no npm

Desenvolvimento

npm install
npm run build
npm test                              # 78 contract tests, no network, no credentials
node scripts/verify-confirm-gate.mjs  # 17 assertions on the publish gate

Os testes de contrato simulam os clientes do Google e verificam o comportamento das chamadas, portanto, são executados em qualquer lugar, inclusive no CI. Os críticos para a segurança estão em test/contract/safety.test.ts — uma falha lá é um bloqueador de lançamento.

Três documentos cobrem o detalhe de engenharia:

• docs/DESIGN.md — por que a arquitetura de segurança tem a forma que tem
• docs/API-NOTES.md — comportamentos da API do Google que são não documentados, fáceis de perder ou ativamente enganosos
• docs/TESTING.md — matriz de rastreabilidade mapeando cada ferramenta para seu método de API, escopo, reversibilidade, cota e testes de cobertura, além das lacunas conhecidas

Requisitos

Node.js >= 20.

Licença

Apache-2.0