GHB MCP
Provides read-only access to allowlisted Google Ads customer accounts by running GAQL SELECT queries for reporting and analysis.
Provides read-only access to allowlisted Google Analytics 4 properties, including running report queries and reading admin metadata such as data streams, key events, custom dimensions, and custom metrics.
Provides read-only access to allowlisted Google Tag Manager resources, including containers, workspaces, tags, triggers, variables, folders, and version information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GHB MCPrun a GA4 report of sessions by source for the last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Ferramenta | Função | Limites |
| Lista os recursos da configuração local | Não verifica conectividade ou permissão no Google |
|
| 1–10 métricas, até 9 dimensões e 1000 linhas; paginação manual por |
| Propriedade, data streams, key events, dimensões e métricas personalizadas | Coleções aceitam |
| Container, workspaces, status, tags, triggers, variáveis, pastas, versão e cabeçalhos de versões | Gramática fechada de caminhos; coleções aceitam |
| Consulta SELECT GAQL | Até 12000 caracteres, uma consulta sem |
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: ga4-mcp
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 .envEdite .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.
Variável | Uso |
| Token OAuth de curta duração, informado localmente |
| IDs numéricos de propriedade, separados por vírgula |
| Caminhos exatos |
| IDs de cliente com 10 dígitos, sem hífens, separados por vírgula |
| ID do gerente usado para acesso delegado, opcional, com 10 dígitos |
| Versão REST, padrão |
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.jsOs 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.
Available Tools
5 toolsconnection_infoBRead-only
Mostra recursos explicitamente autorizados na configuração local.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully clarifies that results come from local configuration rather than a live remote API, consistent with openWorldHint=false, but it says nothing about what is returned, caching, or how authorization state is determined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly a symptom of under-specification rather than disciplined concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description carries the full burden of explaining what the agent gets back, yet it never describes the return shape (a list of resources? scopes? connection names?). It is adequate as a label but thin for a tool whose only value is its output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters (empty properties, additionalProperties=false), so per the rubric the baseline is 4. There is nothing for the description to disambiguate on the input side.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Mostra' (shows) and the scope 'recursos explicitamente autorizados na configuração local' give a rough sense of purpose, and 'local configuration' does distinguish it from the remote-API siblings (gtm_read, ga4_admin_read, ga4_report, google_ads_search). However, 'recursos' is left undefined — an agent cannot tell whether these are scopes, APIs, accounts, or datasets, so the purpose remains vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains no when-to-use guidance, no prerequisites, and no reference to any alternative tool. It never says to call this before the read tools to verify authorization, which is the obvious usage context given the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ga4_admin_readCRead-only
Lê configurações de propriedade GA4 autorizada.
| Name | Required | Description | Default |
|---|---|---|---|
| resource | Yes | ||
| pageToken | No | ||
| propertyId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The word 'autorizada' hints that an authorized property is required, adding a small amount of context, but pagination behavior (pageToken) and per-resource behavior are undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short, front-loaded sentence with no waste, but its brevity comes from under-specification rather than discipline. Nothing extraneous, yet nothing beyond the minimum is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with 0% schema coverage and no output schema, the description is far too thin. It does not describe what is returned per resource type or how results are paged, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no parameter meaning at all. It never explains the 'resource' enum values, nor that 'pageToken' exists for paging through large collections, leaving the agent to infer everything from the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Lê') and resource ('configurações de propriedade GA4'), which separates it from the reporting sibling ga4_report. However, it never mentions the resource kinds actually selectable (dataStreams, keyEvents, customDimensions, customMetrics), so the scope of 'configurações' stays vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no explicit distinction from siblings such as ga4_report or gtm_read. Nothing tells the agent whether this is for admin metadata versus analytics data, nor when to prefer it over the alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ga4_reportCRead-only
Consulta relatório GA4 autorizado, até 1000 linhas; offset permite paginação.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| endDate | Yes | ||
| metrics | Yes | ||
| startDate | Yes | ||
| dimensions | No | ||
| propertyId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that — a hard 1000-row output cap and that offset drives pagination — but says nothing about authorization requirements or rate limits implied by 'autorizado'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no padding, and the row cap and pagination constraint are stated up front. It is efficient, though extremely terse given the tool's 7 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, 4-required tool with no output schema and zero schema description coverage, the description leaves too much unsaid: date formats, metric/dimension naming rules, propertyId format, and response shape are all missing. The line cap and pagination note are not enough to call it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 7 parameters, so the description carries the full burden and largely fails it. It clarifies limit and offset semantics only, leaving all four required parameters (propertyId, startDate, endDate, metrics) with no format or meaning guidance in either place.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Consulta relatório GA4'), and adds scope constraints (up to 1000 rows, offset pagination). It does not, however, distinguish this tool from sibling reads such as ga4_admin_read or gtm_read, so the agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no exclusions, and no mention of the alternative sibling tools. The agent gets an implied 'this retrieves reports' context but nothing that tells it when to pick this over ga4_admin_read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
google_ads_searchBRead-only
Executa uma consulta SELECT GAQL em conta autorizada; aceita pageToken.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| pageToken | No | ||
| customerId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, and non-destructive, so the safety profile is covered. The description adds that the account must be authorized and that pageToken enables pagination, which is useful context, but says nothing about rate limits, result caps, or error behavior on invalid GAQL.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with no filler, front-loading the core action. It is terse to the point of leaving gaps, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, 0% schema description coverage, and three parameters, the description is too thin: customerId is unexplained, the return shape is unknown, and pagination behavior beyond 'accepts pageToken' is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It signals that 'query' must be a GAQL SELECT statement and that 'pageToken' is for paging, but customerId and its 10-digit format are left entirely to the schema pattern.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (executa) and resource (consulta SELECT GAQL) scoped to an authorized account. GAQL is unique to Google Ads, which implicitly separates it from the ga4/gtm siblings, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over ga4_report or gtm_read, nor any prerequisite beyond 'conta autorizada'. The read-only nature implied by SELECT is the only usage signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gtm_readBRead-only
Lê container, workspaces, status, tags, triggers, variáveis, pastas e versões autorizados.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| pageToken | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a real behavioral detail — 'autorizados' indicates only resources the caller is authorized to see are returned — but says nothing about pagination despite exposing a pageToken.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with the verb front-loaded. Nothing is padded, though the noun-list style trades brevity for precision about scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 0% parameter documentation, the description should explain the required 'path' format and how pagination works — it does neither. An agent can guess the tool's domain but not how to construct a valid call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% on both parameters, so the description carries the full burden and fails it: 'path' (the GTM container/entity path, required, ≤250 chars) and 'pageToken' receive no explanation of format or purpose. The resource list hints at what path may select, but pagination semantics are completely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Lê') plus an enumerated set of GTM resources (container, workspaces, tags, triggers, variables, folders, versions), so the domain and operation are unambiguous. It stops short of distinguishing itself from siblings (ga4_admin_read, google_ads_search), though those clearly target different products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the resource list suggests reading GTM configuration entities, but there is no statement of when to choose this over the read siblings or any preconditions. No exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0-rc.2- First observed
connection_info - First observed
ga4_admin_read - First observed
ga4_report - First observed
google_ads_search - First observed
gtm_read
TDQS
Scored across 5 tools
Each tool maps to a distinct platform/action: local authorization info (connection_info), GTM reads, GA4 admin reads, GA4 reporting, and Ads queries. Only connection_info could overlap slightly with gtm_read in that both surface authorized resources, but the scopes are clearly separate.
Four of five tools follow a clean platform_action pattern (gtm_read, ga4_admin_read, ga4_report, google_ads_search) with clear snake_case naming. connection_info breaks the platform-prefix convention but remains readable and unambiguous.
Five tools is a reasonable, tight scope for a read-only tri-platform MCP. It is slightly thin given three distinct products are covered, but no tool feels redundant or filler.
The surface is entirely read-only, so no create/update/publish operations exist for GTM tags, GA4 config, or Ads entities, and GTM reporting/version publishing is absent. If read-only is intentional the read coverage is decent, but agents wanting to modify anything hit a dead end.
Maintenance
Related MCP Connectors
Read-only Google Analytics 4 MCP server for AI assistants.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Read-only Google Search Console and Google Analytics for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables querying Google Analytics 4 data through MCP tools for running reports, listing properties, getting real-time metrics, and exploring metadata.14 npmMIT
- AlicenseNot gradedqualityCmaintenanceRead-only access to Google Analytics 4 reporting data, including traffic overview, top pages, traffic sources, and conversion events, supporting custom report queries via MCP.MIT
- AlicenseAqualityAmaintenanceEnables MCP clients to query Google Analytics 4 reporting and configuration data through 27 read-only tools, including pivots, funnels, realtime reports, Admin API inspection, and diagnostics, with identifiers redacted by default.2762 npmApache 2.0
- AlicenseBqualityBmaintenanceEnables read-only Google Analytics 4 reporting through MCP, including daily summaries, top pages, acquisition, events, realtime activity, metadata, and custom reports with CSV/JSON output.8MIT