GHB MCP

Candidato 0.1.0-rc.2 para um servidor MCP local de somente leitura de Google Analytics 4, Google Tag Manager e Google Ads. Destina-se a análises em recursos explicitamente autorizados por quem opera o servidor.

English: Local, read-only MCP server for allowlisted GA4, GTM and Google Ads resources. Licensed under the MIT License.

Licença: MIT, permitindo uso, modificação e redistribuição, inclusive comercial, conforme seus termos. Consulte LICENSING.md. Este é um candidato testado com dados sintéticos; não há garantia de elegibilidade para programas de OSS.

O que funciona

Não há ferramentas de criação, edição, pausa, exclusão, publicação, proposta ou aprovação. Variáveis antigas de habilitação de escrita não são usadas. Os únicos POST ao Google são os endpoints de consulta runReport e googleAds:search. Erros de sintaxe GAQL e incompatibilidade entre métricas/dimensões são validados também pelo Google.

Related MCP server: google-analytics-mcp-server

Instalação local

Requisitos: Node.js 24, npm, projeto Google Cloud próprio com as APIs necessárias habilitadas e acesso aos recursos. Use um ambiente e usuário de teste para começar. O servidor não obtém, renova ou armazena tokens; não abre serviço HTTP, banco de dados ou porta de rede.

npm ci --ignore-scripts
npm run check
cp .env.example .env
chmod 600 .env

Edite .env somente no seu computador. Não envie esse arquivo ao GitHub nem coloque segredos em prompts ou argumentos de linha de comando. As listas de recursos começam vazias quando as variáveis são omitidas; nesse caso todas as consultas são bloqueadas. Os IDs do modelo são fictícios. Substitua-os por recursos que você está autorizado a consultar, localmente.

Obtenha o access token fora deste servidor, usando o fluxo OAuth documentado pelo Google e um projeto próprio. Não reutilize credenciais de uma implantação existente. Escopos recomendados: https://www.googleapis.com/auth/analytics.readonly, https://www.googleapis.com/auth/tagmanager.readonly e, se Ads for necessário, https://www.googleapis.com/auth/adwords. Solicite somente os serviços usados. O escopo Ads permite mais que leitura; use usuário com função de leitura no provedor. Este servidor restringe os endpoints, mas não inspeciona os escopos efetivamente concedidos. Quando o token expirar, obtenha outro fora do servidor e reinicie o processo. Tokens revogados ou insuficientes causam erro genérico de consulta.

A documentação de migração informa que o acesso Google Ads passou a ser associado ao projeto OAuth em setembro de 2026; o servidor não coleta developer token. Confirme os requisitos atuais na documentação Google Ads. Consulte também os escopos OAuth e o calendário de versões. v24 é uma escolha conservadora do candidato; futuras versões podem exigir revisão de campos e consultas.

Cliente MCP por stdio

Exemplo de configuração do cliente (adapte os caminhos absolutos):

{
  "mcpServers": {
    "ghb-mcp": {
      "command": "node",
      "args": ["--env-file=/caminho/GHB-MCP/.env", "/caminho/GHB-MCP/server.js"]
    }
  }
}

Para execução direta use node --env-file=.env server.js. npm start usa variáveis já exportadas pelo ambiente e não carrega .env automaticamente. O processo aguarda mensagens MCP no stdin; stdout é reservado ao protocolo. Não há OAuth hospedado, conexão remota por URL, multiusuário ou implantação pronta. Use um cliente que suporte subprocessos stdio.

Exemplos fictícios de argumentos:

{"propertyId":"123","startDate":"2026-01-01","endDate":"2026-01-31","metrics":["sessions"],"dimensions":["date"],"limit":100}

{"path":"accounts/1/containers/2/workspaces/3/tags"}

{"customerId":"0000000000","query":"SELECT campaign.id, campaign.name FROM campaign LIMIT 10"}

Segurança e limites

As respostas podem conter dados pessoais, nomes de campanha, código de tags ou informações comerciais. Autorizar um recurso permite que o cliente MCP e seu modelo recebam as respostas de consulta daquele recurso. Avalie as políticas do cliente antes de conectar contas. Conteúdo de tags e nomes deve ser tratado como dado não confiável, nunca como instrução.

Cada requisição tem timeout de 25 segundos, bloqueia redirecionamentos e limita a resposta a 5 MiB. Não há repetição automática, cache, filtro de PII, rate limit global ou paginação automática. Consultas consomem cotas e podem consumir orçamento de APIs habilitadas. O retorno de listas contém somente a página atual. Erros são genéricos para evitar refletir respostas sensíveis. O processo tem o acesso do usuário local que o iniciou; proteja arquivos, máquina e cliente MCP.

Testes e revisão

npm test
npm run check
npm audit --omit=dev
node scripts/scan.js

Os testes usam dados sintéticos, transporte MCP em memória e subprocesso stdio; as chamadas Google usam fetch simulado. Nenhuma consulta real é necessária. O scanner é heurístico, ignora node_modules e não substitui revisão humana. Antes de publicar alterações, confira também o arquivo compactado final, dependências e avisos de licença. Os resultados operacionais da revisão ficam fora deste candidato, para evitar carregar metadados privados.

Veja CONTRIBUTING.md, SECURITY.md e THIRD_PARTY_NOTICES.md.