gtm-ga4

mcp-gtm-ga4

MCP server for Google Tag Manager and GA4 -- tag management, consent auditing, workspace versioning, and analytics reporting via Claude.

Features

• 14 tools spanning GTM workspace management (tags, triggers, variables), consent compliance auditing, workspace preview/versioning, and GA4 reporting
• 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-ga4

Or clone and build:

git clone https://github.com/mharnett/mcp-gtm-ga4.git
cd mcp-gtm-ga4
npm install
npm run build

Configuration

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
GOOGLE_APPLICATION_CREDENTIALS	Yes	Path to a Google credential JSON key file (service account or authorized-user — see Authentication below)
GTM_ACCOUNT_ID	Yes	GTM account ID
GTM_CONTAINER_ID	Yes	GTM container ID
GA4_PROPERTY_ID	Yes	GA4 property ID
GTM_SANDBOX_WORKSPACE_ID	No	Override workspace ID (auto-detects Default Workspace if omitted)
MCP_SERVER_NAME	No	Server name (defaults to package name mcp-gtm-ga4)

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_user keyfile the auth subcommand 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.cjs

The 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.edit.containers	gtm_create_tag, gtm_update_tag, gtm_create_variable, gtm_update_variable, gtm_delete_variable, tag/trigger/variable reads
tagmanager.edit.containerversions	gtm_create_version
tagmanager.publish	gtm_create_version, gtm_preview (quick preview)
analytics.readonly	gtm_ga4_run_report, gtm_ga4_realtime_report, gtm_ga4_list_custom_dimensions
analytics.edit	gtm_ga4_create_custom_dimension

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-ga4

Claude 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_update_tag, gtm_create_tag, gtm_preview, 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

GTM Tags

Tool	Description
gtm_list_tags	List all tags in the workspace with consent status and firing triggers
gtm_get_tag	Get full tag configuration by tag ID
gtm_update_tag	Update an existing tag (merge patch via JSON)
gtm_create_tag	Create a new tag from a JSON definition

GTM Structure

Tool	Description
gtm_list_triggers	List all triggers (ID, name, type)
gtm_list_variables	List all variables (ID, name, type)

GTM Consent

Tool	Description
gtm_audit_consent	Audit all tags for consent configuration compliance

GTM Workspace

Tool	Description
gtm_preview	Generate a quick preview of the current workspace
gtm_create_version	Create a new container version from the workspace

GA4 Reports

Tool	Description
gtm_ga4_run_report	Run a GA4 report with dimensions, metrics, date range, and filters
gtm_ga4_realtime_report	Run a GA4 realtime report (last 30 minutes)

GA4 Admin

Tool	Description
gtm_ga4_list_custom_dimensions	List all custom dimensions for the property
gtm_ga4_create_custom_dimension	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: pino with pino-pretty
• Transport: MCP SDK stdio transport

License

MIT

Author

Built by Mark Harnett / drak-marketing