mcp-gtm-ga4
This MCP server lets Claude inspect GTM/GA4 configuration and reporting, with optional write-gated actions for GTM workspace management and GA4 admin.
Check connectivity and get GTM container/workspace, GA4 property, and server version context.
List and inspect GTM tags, triggers, and variables in the sandbox workspace.
Audit tags for consent compliance and receive recommendations.
Generate a GTM Preview URL for the sandbox workspace.
Run GA4 historical reports with dimensions, metrics, date ranges, limits, and simple equality filters.
Run GA4 realtime reports for the last 30 minutes.
List GA4 custom dimensions for the property.
When
GTM_GA4_MCP_WRITE=true, expose write tools to create/update tags, create/update/delete variables, create container versions, and create GA4 custom dimensions—restricted to the resolved sandbox workspace.
Provides tools for managing Google Tag Manager workspaces, tags, triggers, variables, consent auditing, and container versioning.
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., "@mcp-gtm-ga4 audit consent compliance for all tags"
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.
mcp-gtm-ga4
MCP server for Google Tag Manager and GA4 -- tag management, consent auditing, workspace versioning, and analytics reporting via Claude.
Quick install
Claude Code, one line (replace the placeholder values with your own; see Configuration and Authentication for how to get them):
claude mcp add --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json --env GTM_ACCOUNT_ID=YOUR_GTM_ACCOUNT_ID --env GTM_CONTAINER_ID=YOUR_GTM_CONTAINER_ID --env GA4_PROPERTY_ID=YOUR_GA4_PROPERTY_ID --transport stdio mcp-gtm-ga4 -- npx -y mcp-gtm-ga4All write operations are sandbox-checked: the server refuses to write to a workspace that is not the resolved sandbox workspace.
Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), then fully quit and restart Claude Desktop:
{
"mcpServers": {
"mcp-gtm-ga4": {
"command": "npx",
"args": ["-y", "mcp-gtm-ga4"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json",
"GTM_ACCOUNT_ID": "YOUR_GTM_ACCOUNT_ID",
"GTM_CONTAINER_ID": "YOUR_GTM_CONTAINER_ID",
"GA4_PROPERTY_ID": "YOUR_GA4_PROPERTY_ID"
}
}
}
}Add this to ~/.codex/config.toml:
[mcp_servers.mcp-gtm-ga4]
command = "npx"
args = ["-y", "mcp-gtm-ga4"]
[mcp_servers.mcp-gtm-ga4.env]
GOOGLE_APPLICATION_CREDENTIALS = "/path/to/credentials.json"
GTM_ACCOUNT_ID = "YOUR_GTM_ACCOUNT_ID"
GTM_CONTAINER_ID = "YOUR_GTM_CONTAINER_ID"
GA4_PROPERTY_ID = "YOUR_GA4_PROPERTY_ID"Related MCP server: Analytics MCP
Features
18 tools (11 read, 7 write-gated) spanning GTM workspace management (tags, triggers, variables), consent compliance auditing, workspace preview/versioning, and GA4 reporting. The server starts read-only; set
GTM_GA4_MCP_WRITE=trueto expose the 7 write tools (gtm_create_tag,gtm_update_tag,gtm_create_variable,gtm_update_variable,gtm_delete_variable,gtm_create_version,gtm_ga4_create_custom_dimension)Sandbox safety -- all write operations verify they target the resolved workspace, refusing to write to non-sandbox workspaces
Multi-client support -- configure per-client via environment variables
Auto-detects Default Workspace ID -- no need to manually specify workspace IDs unless using a custom sandbox
Installation
npm install mcp-gtm-ga4Or clone and build:
git clone https://github.com/mharnett/mcp-gtm-ga4.git
cd mcp-gtm-ga4
npm install
npm run buildConfiguration
Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.
Runtime configuration is via environment variables.
Variable | Required | Description |
| Yes | Path to a Google credential JSON key file (service account or authorized-user — see Authentication below) |
| Yes | GTM account ID |
| Yes | GTM container ID |
| Yes | GA4 property ID |
| No | Override workspace ID (auto-detects Default Workspace if omitted) |
| No | Server name (defaults to package name |
See config.example.json for a reference template. The only value read from disk is oauth.scope (in an optional config.json) — the single source of truth for the OAuth scope the onboarding paths request. If no config.json is present, the committed minimum scope is used.
Authentication
This MCP supports two auth models. Both feed the same GOOGLE_APPLICATION_CREDENTIALS runtime path.
Precedence & mechanism
There is no runtime service-account-vs-OAuth toggle. Both models converge on a
single slot — GOOGLE_APPLICATION_CREDENTIALS — which the runtime hands to
GoogleAuth({ keyFile }). Whichever file you point that env var at is the
credential:
a service-account JSON key (option 1 below), or
the
authorized_userkeyfile theauthsubcommand writes (option 2) — a file that plugs into the exact same slot.
So the only real precedence rule is failure handling: an explicitly-configured
keyfile is used; when GOOGLE_APPLICATION_CREDENTIALS is unset the server fails
loudly at startup with an onboarding error naming both the service-account path
and the auth OAuth helper. It deliberately does not fall back to Google's
Application Default Credentials (gcloud user creds / GCE metadata server) — no
silent machine-local default, no silent runtime failover.
1. Service account (primary, recommended for unattended/server use)
Create a service account in your GCP project, download its JSON key, grant it the
GTM container role (on the target GTM container) and GA4 property access, and
point GOOGLE_APPLICATION_CREDENTIALS at the key file. No OAuth flow, no browser,
no refresh token. This is the recommended path for headless/server/unattended
deployments.
2. User OAuth (interactive, for users without a service account)
If you can't use a service account, mint a user credential with your own Google OAuth client (a "Desktop app" OAuth 2.0 Client ID created in your own GCP project — enable the Tag Manager API and the Google Analytics Admin + Data APIs). Two equivalent onboarding commands, both hardened with PKCE (RFC 7636, S256) and both requesting the scope from config.json (oauth.scope) so they never drift:
export GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
export GOOGLE_CLIENT_SECRET=your-client-secret
# Option A: write an authorized_user credential file directly
node dist/index.js auth --output ./gtm-ga4-credentials.json
# then set GOOGLE_APPLICATION_CREDENTIALS=./gtm-ga4-credentials.json
# Option B: the standalone helper (prints GOOGLE_REFRESH_TOKEN + a ready-to-save
# authorized_user JSON you can write to a file for GOOGLE_APPLICATION_CREDENTIALS)
node get-refresh-token.cjsThe refresh token / credential is written by you and read from your environment only. Nothing is shared and no OAuth client keyfile is bundled. Do not run the helper with stdout redirected to a shared log — the refresh token is printed to stdout by design.
OAuth scopes requested
The onboarding paths request exactly the scopes this MCP's tools use (from config.example.json → oauth.scope):
Scope | Needed by |
|
|
|
|
|
|
|
|
|
|
tagmanager.readonly is intentionally not requested — the edit scopes already grant read access.
Usage
Claude Code (.mcp.json)
{
"mcpServers": {
"gtm-ga4": {
"command": "node",
"args": ["/path/to/mcp-gtm-ga4/dist/index.js"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
"GTM_ACCOUNT_ID": "1234567890",
"GTM_CONTAINER_ID": "9876543",
"GA4_PROPERTY_ID": "331956119"
}
}
}
}npx
GTM_ACCOUNT_ID=1234567890 \
GTM_CONTAINER_ID=9876543 \
GA4_PROPERTY_ID=331956119 \
GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json \
npx mcp-gtm-ga4Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
Safety
Workspace sandbox protection
All write operations (gtm_create_tag, gtm_update_tag, gtm_create_variable, gtm_update_variable, gtm_delete_variable, gtm_create_version) verify they target the resolved workspace before executing. If a request attempts to write to a different workspace, the server returns a SafetyError and blocks the operation.
This prevents accidental production changes when the MCP server is configured against a sandbox workspace.
Tools
Status
Tool | Description |
| Health check and status overview: GTM container path, workspace ID, GA4 property ID and server version |
GTM Tags
Tool | Description |
| List all tags in the workspace with consent status and firing triggers |
| Get full tag configuration by tag ID |
| Update an existing tag (merge patch via JSON) |
| Create a new tag from a JSON definition |
GTM Structure
Tool | Description |
| List all triggers (ID, name, type) |
| List all variables (ID, name, type) |
| Get full details of a single variable by ID |
| Create a new variable in the sandbox workspace |
| Update a variable (fetch, merge, save) in the sandbox workspace |
| Delete a variable from the sandbox workspace (destructive) |
GTM Consent
Tool | Description |
| Audit all tags for consent configuration compliance |
GTM Workspace
Tool | Description |
| Generate a quick preview of the current workspace |
| Create a new container version from the workspace |
GA4 Reports
Tool | Description |
| Run a GA4 report with dimensions, metrics, date range, and filters |
| Run a GA4 realtime report (last 30 minutes) |
GA4 Admin
Tool | Description |
| List all custom dimensions for the property |
| Create a new custom dimension |
Architecture
GTM API:
googleapis(Tag Manager v2)GA4 Data:
@google-analytics/data(BetaAnalyticsDataClient)GA4 Admin:
@google-analytics/admin(AnalyticsAdminServiceClient)Resilience:
cockatiel(retry, circuit breaker, timeout policies)Logging:
pinowithpino-prettyTransport: MCP SDK stdio transport
License
MIT
Author
Built by Mark Harnett / drak-marketing
Available Tools
11 toolsgtm_audit_consentA
Scan all tags in the sandbox workspace and report consent compliance. Returns tags with no consent, NOT_NEEDED tags, properly configured tags, and recommendations.
Inputs: no named parameters.
gtm_ga4_list_custom_dimensionsA
List all registered custom dimensions for the GA4 property linked to this GTM container.
Inputs: no named parameters.
gtm_ga4_realtime_reportA
Query GA4 Realtime Report (last 30 minutes) for the property linked to this GTM container.
Inputs: metrics, dimensions, dimension_filter.
gtm_ga4_run_reportB
Query GA4 historical report for the property linked to this GTM container.
Inputs: limit, metrics, end_date, dimensions, +2 more.
gtm_get_client_contextA
Health check and status overview. Returns GTM container path, workspace ID, GA4 property ID, and server version. Use this to verify connectivity.
Inputs: no named parameters.
gtm_get_tagA
Get full details of a single tag by ID from the sandbox workspace.
Inputs: tag_id (required).
gtm_get_variableA
Get full details of a single variable by ID from the sandbox workspace.
Inputs: variable_id (required).
gtm_list_tagsA
List all tags in the sandbox GTM workspace with name, type, consent status, and firing triggers.
Inputs: no named parameters.
gtm_list_triggersA
List all triggers in the sandbox GTM workspace.
Inputs: no named parameters.
gtm_list_variablesA
List all variables in the sandbox GTM workspace.
Inputs: no named parameters.
gtm_previewA
Generate a GTM Preview URL for the sandbox workspace.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct GTM or GA4 resource/action: list/get operations are clearly separated by resource type, audit/consent and preview have unique purposes, and the two GA4 report tools are differentiated by live vs. historical data. No two tools appear to do the same thing.
Most tools consistently follow the gtm_<verb>_<object> pattern, with list and get verbs used predictably across resources. Minor deviations like gtm_get_client_context and gtm_preview, plus gtm_ga4_run_report vs. gtm_ga4_realtime_report, introduce slight inconsistency but the overall convention remains readable.
11 tools is a well-scoped size for a GTM/GA4 server covering listing, retrieval, auditing, preview, and reporting. Each tool has a clear purpose and the count does not feel bloated or insufficient.
The set covers the main read-only workflows for GTM inspection, consent auditing, preview URL generation, and GA4 reporting. Missing pieces like a get_trigger operation and write/management operations are minor relative to the apparent read-only/audit-focused intent.
Maintenance
Related MCP Connectors
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Hosted Google Analytics 4 MCP server, with each action switched on or off per account.
Hosted Google Tag Manager MCP server, with each action switched on or off per account.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP Server that provides a conversational interface to Google Tag Manager API, allowing users to manage tags, triggers, variables, and containers through natural language.-
- AlicenseNot gradedqualityDmaintenanceAutomates Google Analytics 4 and Google Tag Manager setup, management, and health monitoring with blueprints, multi-environment support, and MCP tools for AI agents.MIT
- AlicenseAqualityFmaintenanceAn MCP server for the Google Tag Manager API v2 that enables AI assistants to query GTM accounts, containers, tags, triggers, variables, and unpublished changes.241Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server for Google Tag Manager and Google Ads, enabling AI agents to audit, fix, and manage GTM containers and Google Ads campaigns programmatically.106 npmMIT